> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a payout

> Reserve the money and pay a beneficiary in `asset`. `amount` is what they receive; your `source_asset` balance is debited `source_amount` plus `fee`. The destination is validated before any money is reserved, so a refusal (422) leaves nothing behind. The response is the payout as it stands after the payment network has answered — normally `pending`; a payout may be `failed` in its creation response, with the reserved money already released. Requires an `Idempotency-Key`.



## OpenAPI

````yaml /v2/openapi.json post /payouts
openapi: 3.1.0
info:
  title: Jenzy Hermes Multi-asset API
  version: 2.0.0
  description: >-
    Hold and pay out across the assets enabled for your organization. Every
    amount is an exact decimal string beside an `asset` field. Authenticate with
    the same `jz_live_…` API key as `/v1`.
servers:
  - url: https://api.jenzy.com/v2
    description: Production
security: []
paths:
  /payouts:
    post:
      summary: Create a payout
      description: >-
        Reserve the money and pay a beneficiary in `asset`. `amount` is what
        they receive; your `source_asset` balance is debited `source_amount`
        plus `fee`. The destination is validated before any money is reserved,
        so a refusal (422) leaves nothing behind. The response is the payout as
        it stands after the payment network has answered — normally `pending`; a
        payout may be `failed` in its creation response, with the reserved money
        already released. Requires an `Idempotency-Key`.
      parameters:
        - schema:
            type: string
            description: >-
              Required. A key you mint per payout intent (a UUID works). Replays
              of the same key + body return the original response; the same key
              with a different body is a 409.
          required: true
          description: >-
            Required. A key you mint per payout intent (a UUID works). Replays
            of the same key + body return the original response; the same key
            with a different body is a 409.
          name: Idempotency-Key
          in: header
        - $ref: '#/components/parameters/HermesOrg'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayoutCreate'
      responses:
        '201':
          description: >-
            Created. `status` is normally `pending`; it can be `held` (the
            payment network has not yet acknowledged — poll) or already
            `failed`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
        '400':
          description: >-
            Malformed body, missing `Idempotency-Key`, or an `amount` with more
            decimals than the asset carries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: >-
            `insufficient_funds`: your available balance in `source_asset` does
            not cover `source_amount` + fee + reserve, or a shortfall in it must
            clear first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: >-
            `corridor_not_enabled`: `asset` is not enabled for payouts for your
            organization, or `source_asset` is not enabled. Also the access
            codes above.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: >-
            This `Idempotency-Key` was already used with a different request, or
            its original request is still in progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: >-
            The destination is unpayable (`invalid_wallet_address`), the pair is
            `unsupported_pair`, or the amount is outside the corridor
            (`amount_below_minimum`, `limit_exceeded`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: >-
            `rate_unavailable` (no rate to price the fee),
            `service_unavailable`, or the `/v2` shutter is closed
            (`service_maintenance` / `service_incident`) — your
            `Idempotency-Key` is NOT spent by a shutter refusal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - ApiKeyAuth: []
components:
  parameters:
    HermesOrg:
      name: HERMES-ORG
      in: header
      required: false
      description: >-
        The id of one of your Child orgs. The call then acts on that Child org,
        not on your organization. If you do not send it, the call acts on your
        organization. An id that is not one of your Child orgs gives `404`.
      schema:
        type: string
        format: uuid
        example: 3f1c2a9e-8b7d-4e21-9a6f-0c5d4b3e2a10
  schemas:
    PayoutCreate:
      type: object
      properties:
        amount:
          anyOf:
            - type: integer
            - type: string
              pattern: ^\d+(\.\d+)?$
          description: >-
            What the beneficiary receives, in `asset`. Fees are on top, in
            `source_asset`.
          example: '10000.00'
        asset:
          type: string
          minLength: 1
          description: The asset the beneficiary receives.
          example: USDC
        source_asset:
          type: string
          minLength: 1
          description: >-
            The asset you pay from. Defaults to `asset`. A `USD` payout pays
            from `USDC`; any other pair is `unsupported_pair`.
          example: USDC
        destination:
          oneOf:
            - $ref: '#/components/schemas/WalletDestinationCreate'
            - $ref: '#/components/schemas/BeneficiaryDestinationCreate'
          discriminator:
            propertyName: type
            mapping:
              wallet: '#/components/schemas/WalletDestinationCreate'
              beneficiary: '#/components/schemas/BeneficiaryDestinationCreate'
        invoice_document_id:
          type: string
          format: uuid
          description: >-
            Only on a USD payout: the `id` of an invoice you uploaded with `POST
            /v2/documents`. Required when the USD beneficiary is a third party
            (`invoice_required`). One invoice justifies one payout.
      required:
        - amount
        - asset
        - destination
    Payout:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Payout id — your handle for polling and support.
        status:
          type: string
          enum:
            - received
            - validated
            - held
            - submitted
            - pending
            - succeeded
            - failed
            - reversed
          description: >-
            Lifecycle: `held` (money reserved, the payment network has not yet
            acknowledged) → `pending` → `succeeded` | `failed`. `succeeded`,
            `failed` and `reversed` are terminal. A payout may already be
            `failed` in its creation response: the destination was accepted but
            the payment network refused it at once, and the reserved money is
            released. `reversed` means the payout succeeded and was then clawed
            back — it is not a failure and carries no `failure` object.
          example: pending
        asset:
          type: string
          minLength: 1
          description: >-
            An asset code as `GET /v2/assets` lists it — uppercase, never
            compound (`USDC`, `USD`; never `USDC-ETHEREUM`). Network and rail
            live on the payment object.
          example: USDC
        amount:
          type: string
          description: >-
            What the beneficiary receives, as an exact decimal string in
            `asset`.
          example: '10000.00'
        source_asset:
          type: string
          minLength: 1
          description: What you paid from.
          example: USDC
        source_amount:
          type: string
          description: >-
            What is debited from your `source_asset` balance for the beneficiary
            amount; equals `amount` when the assets are the same. Your fee is on
            top.
          example: '10000.00'
        fee:
          type: string
          description: >-
            Jenzy’s payout fee, one total, in `source_asset`. Known at creation.
            On a USD payout: the all-in fee, everything beyond `amount`.
          example: '0.8'
        rate:
          type:
            - string
            - 'null'
          description: >-
            `source_amount ÷ amount` at 8 decimal places — `source_asset` per 1
            `asset` — when the assets differ; null otherwise. Informational: the
            two amounts are the contract.
          example: null
        destination:
          oneOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - wallet
                network:
                  type: string
                address:
                  type: string
                beneficiary_name:
                  type: string
                beneficiary_type:
                  type: string
                  enum:
                    - individual
                    - business
                beneficiary_country:
                  type: string
                beneficiary_date_of_birth:
                  type:
                    - string
                    - 'null'
              required:
                - type
                - network
                - address
                - beneficiary_name
                - beneficiary_type
                - beneficiary_country
                - beneficiary_date_of_birth
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - beneficiary
                beneficiary_id:
                  type: string
                  format: uuid
                  description: >-
                    Only on a USD payout: the `id` of your USD beneficiary that
                    receives the payout.
              required:
                - type
                - beneficiary_id
        failure:
          type:
            - object
            - 'null'
          properties:
            code:
              type: string
              enum:
                - recipient_account_invalid
                - declined
                - provider_unavailable
                - temporarily_unavailable
            message:
              type: string
          required:
            - code
            - message
          description: >-
            Set only when `status` is `failed`: one of the published codes with
            its fixed message. Detail from the payment network is never
            included.
        created_at:
          type: string
          format: date-time
        terminal_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the payout reached `succeeded`, `failed` or `reversed`; null
            while in flight.
        receipt_url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            The public link to the receipt of a USD payout to a saved
            beneficiary. Send it to your beneficiary: the page shows the status
            of the payment, not your fee or rate. Null for every other payout.
            In the sandbox the link is on `track.sandbox.jenzy.com`.
        tx_hash:
          type:
            - string
            - 'null'
          description: >-
            The on-chain hash of a `wallet` payout: an Ethereum transaction hash
            or a Solana signature. Set while the payout is `pending`, from the
            first read that has it, so you can follow the transfer on a block
            explorer. Null before Hermes has the hash, and for each payout that
            is not a `wallet` payout.
          example: null
      required:
        - id
        - status
        - asset
        - amount
        - source_asset
        - source_amount
        - fee
        - rate
        - destination
        - failure
        - created_at
        - terminal_at
        - receipt_url
        - tx_hash
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_error
                - unauthorized
                - forbidden
                - not_found
                - conflict
                - rate_limited
                - internal_error
                - unknown_institution
                - invalid_mobile_number
                - invalid_account_number
                - mobile_number_institution_mismatch
                - service_unavailable
                - sandbox_only
                - insufficient_funds
                - rail_disabled
                - amount_limit_exceeded
                - org_limit_exceeded
                - service_incident
                - service_maintenance
                - onboarding_incomplete
                - access_suspended
                - corridor_not_enabled
                - unsupported_pair
                - invalid_wallet_address
                - rate_unavailable
                - quote_expired
                - quote_used
                - limit_exceeded
                - amount_below_minimum
                - unsupported_asset
                - unsupported_network
                - unsupported_media_type
                - payload_too_large
                - client_ref_used
                - beneficiary_required
                - beneficiary_not_allowed
                - proof_not_expected
                - invalid_beneficiary
                - beneficiary_exists
                - beneficiary_not_active
                - invoice_required
                - prohibited_industry
              description: >-
                Stable identifier a client may branch on — never renamed or
                removed.
            message:
              type: string
          required:
            - code
            - message
      required:
        - error
    WalletDestinationCreate:
      type: object
      properties:
        type:
          type: string
          enum:
            - wallet
        network:
          type: string
          enum:
            - ethereum
            - solana
          description: >-
            The network by name: `ethereum` or `solana`. The asset must be
            supported on it (`invalid_wallet_address` names the supported
            networks otherwise).
          example: ethereum
        address:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            The beneficiary wallet address, checked for shape on every network.
            An Ethereum address in mixed case must carry a valid EIP-55
            checksum; all-lowercase is accepted. Addresses that need a memo or
            destination tag are not supported.
          example: '0x52908400098527886E0F7030069857D2E4169EE7'
        beneficiary_name:
          type: string
          minLength: 1
          description: >-
            Who the money is for. Sent to the payment network as given — it is
            not verified against the account.
          example: Jane Doe
        beneficiary_type:
          type: string
          enum:
            - individual
            - business
          description: Defaults to `individual`.
        beneficiary_country:
          type: string
          minLength: 2
          maxLength: 2
          description: ISO 3166-1 alpha-2 (`KE`).
          example: KE
        beneficiary_date_of_birth:
          type: string
          description: YYYY-MM-DD. Required when `beneficiary_type` is `individual`.
          example: '1990-02-28'
      required:
        - type
        - network
        - address
        - beneficiary_name
        - beneficiary_country
    BeneficiaryDestinationCreate:
      type: object
      properties:
        type:
          type: string
          enum:
            - beneficiary
        beneficiary_id:
          type: string
          format: uuid
          description: >-
            The `id` of your USD beneficiary. A USD payout takes only this
            destination; every other asset takes only an inline destination.
      required:
        - type
        - beneficiary_id
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: 'Your Jenzy API key: `Authorization: Bearer jz_live_…`'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.