> ## 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.

# Create Payout

> Execute a previously-quoted payout.

Execute a previously-quoted payout.

Consumes the `quote_id`; production atomically marks it
used so a second POST with the same quote\_id returns 409
`quote_already_used`. Sandbox skips the consume but mints a
deterministic payout id from (org, quote\_id) so the same
inputs produce the same response.

Status returned is always `pending` at execute time;
partners poll `GET /payouts/:id` (or, in Phase 4, subscribe
to the `payout.*` webhooks) for state changes.


## OpenAPI

````yaml POST /payouts
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:
    post:
      tags:
        - payouts
      summary: Create Payout
      description: |-
        Execute a previously-quoted payout.

        Consumes the ``quote_id``; production atomically marks it
        used so a second POST with the same quote_id returns 409
        ``quote_already_used``. Sandbox skips the consume but mints a
        deterministic payout id from (org, quote_id) so the same
        inputs produce the same response.

        Status returned is always ``pending`` at execute time;
        partners poll ``GET /payouts/:id`` (or, in Phase 4, subscribe
        to the ``payout.*`` webhooks) for state changes.
      operationId: create_payout_payouts_post
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectPayoutExecuteRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectPayoutResponse'
        '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:
    ConnectPayoutExecuteRequest:
      properties:
        quote_id:
          type: string
          maxLength: 128
          minLength: 1
          title: Quote Id
          description: >-
            From a prior POST /payouts/quote response. Single-use: a second POST
            /payouts with the same quote_id returns 409 ``quote_already_used``.
      additionalProperties: false
      type: object
      required:
        - quote_id
      title: ConnectPayoutExecuteRequest
      description: |-
        Request body for POST /payouts.

        Just the quote_id — every other parameter (asset, amount,
        destination, route) is locked in the quote and we look it up
        server-side. This is the contract that lets the quote act as
        a price promise: the partner can't tamper with the inputs
        between the price they showed the user and what we execute.
    ConnectPayoutResponse:
      properties:
        id:
          type: string
          title: Id
          description: >-
            Partner-facing payout id (e.g. ``pay_...``). Opaque and stable
            across the payout's lifetime.
        status:
          type: string
          enum:
            - pending
            - broadcast
            - delivered
            - failed
          title: Status
        quote:
          $ref: '#/components/schemas/ConnectPayoutQuoteSnapshot'
        estimated_delivery_at:
          type: string
          format: date-time
          title: Estimated Delivery At
          description: >-
            Server-computed best estimate. Updated as state advances (a quote
            estimate of 90s shrinks to 20s after the bridge broadcast lands).
            Partners can drive UI countdowns off this.
        tracking_url:
          type: string
          title: Tracking Url
          description: >-
            Public URL the partner can share with their user or embed for
            self-service tracking. The hosted page renders the same timeline as
            ``GET /payouts/:id``.
      type: object
      required:
        - id
        - status
        - quote
        - estimated_delivery_at
        - tracking_url
      title: ConnectPayoutResponse
      description: |-
        Response body for POST /payouts and base for GET /payouts/:id.

        Status transitions monotonically forward (pending → broadcast
        → delivered, or any → failed). Partners can poll this endpoint
        or subscribe to ``payout.broadcast`` / ``payout.delivered`` /
        ``payout.failed`` webhooks (Phase 4) for state changes.
    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.
    ConnectPayoutQuoteSnapshot:
      properties:
        quote_id:
          type: string
          title: Quote Id
        user_sends:
          type: string
          title: User Sends
        recipient_gets:
          type: string
          title: Recipient Gets
        fee_total_usd:
          type: string
          title: Fee Total Usd
        route:
          $ref: '#/components/schemas/ConnectPayoutRoute'
      type: object
      required:
        - quote_id
        - user_sends
        - recipient_gets
        - fee_total_usd
        - route
      title: ConnectPayoutQuoteSnapshot
      description: |-
        A condensed copy of the quote, embedded in the execute /
        detail response so partners can render the executed terms
        without a separate /payouts/quote lookup.

        Notably omits ``insufficient_funds`` (only relevant at quote
        time) and ``recommendation`` (advisory, not part of what was
        executed). Keeps the snapshot focused on what actually
        happened.
    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/<code>``. 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.
    ConnectPayoutRoute:
      properties:
        type:
          type: string
          enum:
            - native
            - bridge
          title: Type
        from_network:
          type: string
          title: From Network
          description: >-
            Lowercase network code we'll *send from* (where the user's funds are
            held). For native payouts equals ``to_network``.
        to_network:
          type: string
          title: To Network
          description: Lowercase network code where the recipient receives.
        estimated_seconds:
          type: integer
          minimum: 0
          title: Estimated Seconds
          description: >-
            Expected time from execute to delivery. Native is tens of seconds;
            bridge is 60-180s depending on destination chain finality.
      type: object
      required:
        - type
        - from_network
        - to_network
        - estimated_seconds
      title: ConnectPayoutRoute
      description: |-
        Routing summary baked into every quote.

        Partners surface this to their user as "via Solana → Tron,
        ~90s" so the user understands the path before confirming.
  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.

````