> ## Documentation Index > Fetch the complete documentation index at: https://docs.zopay.cash/llms.txt > Use this file to discover all available pages before exploring further. # Get Payout > Status + timeline for an existing payout. Status + timeline for an existing payout. Sandbox returns a fully-delivered timeline so partners see the happy-path shape immediately; production reads `transaction_saga_events` for the real progression. Either way the shape is identical. Cross-tenant lookups collapse to 404 `payout_not_found` in production. Sandbox doesn't enforce tenant scoping (there is no real payout to scope) and returns a canned body for any well-formed id. ## OpenAPI ````yaml GET /payouts/{payout_id} openapi: 3.1.0 info: title: ZoPay Connect API description: >- B2B partner API for crypto custody, deposits, and payouts. Authenticate every request with a Bearer token (``sk_live_…`` for production, ``sk_test_…`` for sandbox). version: v1 servers: - url: https://api.zopay.cash/connect/v1 description: Production - url: https://dev.api.zopay.cash/connect/v1 description: Development security: - BearerAuth: [] tags: - name: capabilities description: >- Static product catalog: which assets, networks, and fiat valuations this tenant can use. Poll on app startup to drive every UI surface (network pickers, fee warnings, fiat selection). - name: addresses description: >- Per-user deposit addresses. Mint with ``external_ref`` to attribute to one of your users; omit for a tenant-treasury (pooled) address. - name: payment-intents description: >- Single-use payment requests. Mint an intent for a specific amount + currency set; we expand it to per-network deposit addresses. Pass ``external_ref`` to attribute the intent to one of your users for downstream webhook reconciliation. - name: balances description: >- Per-user or tenant-wide balance snapshot with multi-fiat valuation (USD, PEN, EUR, MXN, ARS, COP, DOP). - name: transactions description: >- Unified ledger covering deposits, payouts, internal transfers, and (after Phase 4) conversions and ramps. - name: payouts description: >- Outbound money movement: get a signed quote, then execute it. Quote IDs are single-use and expire in 60s. - name: conversions description: '[Coming soon] Crypto-to-crypto conversions.' - name: ramps description: '[Coming soon] Fiat <-> crypto hosted-checkout sessions.' - name: webhooks description: '[Coming soon] Subscribe to event streams + replay past events.' - name: health description: >- Auth + connectivity probe. Use to validate your API key works before depending on a priced endpoint. - name: test-helpers description: >- Sandbox-only simulators. Let you exercise webhook handlers and downstream state transitions without real testnet activity. Routes return 404 to ``sk_live_…`` keys. paths: /payouts/{payout_id}: get: tags: - payouts summary: Get Payout description: |- Status + timeline for an existing payout. Sandbox returns a fully-delivered timeline so partners see the happy-path shape immediately; production reads ``transaction_saga_events`` for the real progression. Either way the shape is identical. Cross-tenant lookups collapse to 404 ``payout_not_found`` in production. Sandbox doesn't enforce tenant scoping (there is no real payout to scope) and returns a canned body for any well-formed id. operationId: get_payout_payouts__payout_id__get parameters: - name: payout_id in: path required: true schema: type: string title: Payout Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ConnectPayoutDetailResponse' '400': description: >- Invalid request. The body or query parameters failed validation. ``error.code`` names the specific failure (e.g. ``invalid_request``, ``catalog_invalid``, ``min_usdt_amount_requires_solana``); ``error.param`` names the offending field when applicable. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '401': description: >- Authentication failed. ``error.code`` distinguishes ``authentication_required`` (missing / malformed / unknown key) from ``expired_credential`` (key matched but past its ``expires_at``). Rotate the key in the admin panel for the latter. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '403': description: >- The key is valid but lacks permission for this endpoint. ``error.code`` is ``forbidden_scope`` when the key is missing a scope; ``account_pending_approval`` when the org is not yet active for Connect. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '404': description: >- Resource not found in this tenant. Same envelope shape is returned for genuinely-missing IDs and for cross-tenant accesses -- existence under other tenants is not leakable. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '409': description: >- Conflict. Most commonly ``idempotency_conflict`` -- the same ``Idempotency-Key`` was reused with a different body. Generate a fresh key or replay the original body. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '422': description: >- Validation failed. Runtime translates FastAPI / Pydantic validation errors into the same Connect envelope you see on 400s; this status is emitted when the request shape is structurally wrong (missing required field, wrong type). content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '429': description: >- Rate limited. Back off and retry. ``error.code`` is ``rate_limited``; per-key throughput is documented via ``rate_limit_rps`` on the API key. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '500': description: >- Internal server error. ``error.code`` is ``internal_error``. The request can usually be safely retried with the same ``Idempotency-Key``. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' '501': description: >- Endpoint is declared in the router but its implementation has not shipped yet (``error.code = not_yet_available``). Pinned in the schema so SDK generators emit the endpoint with a typed error rather than skipping it. content: application/json: schema: $ref: '#/components/schemas/ConnectErrorEnvelope' security: - BearerAuth: [] components: schemas: ConnectPayoutDetailResponse: properties: id: type: string title: Id status: type: string enum: - pending - broadcast - delivered - failed title: Status timeline: items: $ref: '#/components/schemas/ConnectPayoutTimelineEntry' type: array title: Timeline fees_paid_usd: type: string title: Fees Paid Usd description: >- Actual fee paid, may differ from the quoted fee_total_usd for routes where the gas oracle came in cheaper / more expensive than expected. Stable after status=delivered. final_recipient_amount: type: string title: Final Recipient Amount description: >- Actual amount that landed at the destination. Equals the quoted ``recipient_gets`` for native routes; for bridge routes it may differ marginally. type: object required: - id - status - timeline - fees_paid_usd - final_recipient_amount title: ConnectPayoutDetailResponse description: |- Response body for GET /payouts/:id. Extends the execute response with the timeline + actual fees + final amount once known. ConnectErrorEnvelope: properties: error: $ref: '#/components/schemas/ConnectErrorBody' description: >- Error details. Always present on a non-2xx response from /connect/v1. type: object required: - error title: ConnectErrorEnvelope description: |- Top-level wrapper for every /connect/v1 failure response. Wire shape:: {"error": {"type": ..., "code": ..., "message": ..., ...}} The wrapper is intentional: it keeps error bodies syntactically distinct from success bodies, so polymorphic partner code paths that read the same JSON for both states can branch on the presence of the ``error`` key. ConnectPayoutTimelineEntry: properties: step: type: string enum: - queued - source_confirmed - bridge_broadcast - delivered - failed title: Step at: type: string format: date-time title: At tx_hash: anyOf: - type: string - type: 'null' title: Tx Hash description: >- On-chain transaction hash if this step produced one (source_confirmed, bridge_broadcast, delivered). Null for steps that don't (queued). type: object required: - step - at title: ConnectPayoutTimelineEntry description: One row in the GET /payouts/:id timeline. ConnectErrorBody: properties: type: type: string title: Type description: >- Stripe-style error category. One of: ``invalid_request_error``, ``authentication_error``, ``not_found_error``, ``rate_limit_error``, ``idempotency_error``, ``api_error``. Stable across minor versions; branch on this for top-level error routing. examples: - invalid_request_error code: type: string title: Code description: >- Machine-stable identifier for the specific failure. More specific than ``type``. Examples: ``invalid_request``, ``authentication_required``, ``expired_credential``, ``forbidden_scope``, ``account_pending_approval``, ``resource_not_found``, ``idempotency_conflict``, ``rate_limited``, ``internal_error``, ``not_yet_available``. Match on ``code`` in your client's error handler -- never parse ``message``. examples: - authentication_required message: type: string title: Message description: >- Human-readable explanation. Safe to surface in your own UI but may be reworded between releases -- never branch on the string. examples: - >- Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_... doc_url: type: string title: Doc Url description: >- Link to docs explaining this ``code``. Constructed as ``https://docs.zopay.cash/errors/``. Surface this in support tickets so we can investigate without a round-trip. examples: - https://docs.zopay.cash/errors/authentication_required param: anyOf: - type: string - type: 'null' title: Param description: >- Names the offending input field when the error is input-shape-related (mostly ``invalid_request_error`` from 400 and 422). Absent on auth, scope, rate-limit, and internal errors. examples: - currencies type: object required: - type - code - message - doc_url title: ConnectErrorBody description: |- The ``error`` object inside every /connect/v1 failure response. Mirrors ``ConnectError.to_envelope()`` in ``app/api/connect/errors.py``. Field set is locked -- adding a new field is a partner-visible contract change and requires a coordinated docs + schema update. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Connect API key (sk_live_… or sk_test_…) description: >- Paste your Connect API key (sk_live_… for production, sk_test_… for sandbox) without the ``Bearer `` prefix. Mint and rotate keys from the admin panel. ````