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

# List payouts

> Your payouts, newest first, optionally filtered by `asset` and `status`. Pass `next_before_id` back as `before_id` for the next page; null means done.



## OpenAPI

````yaml /v2/openapi.json get /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:
    get:
      summary: List payouts
      description: >-
        Your payouts, newest first, optionally filtered by `asset` and `status`.
        Pass `next_before_id` back as `before_id` for the next page; null means
        done.
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 200
            description: Page size, 1-200 (default 50).
          required: false
          description: Page size, 1-200 (default 50).
          name: limit
          in: query
        - schema:
            type: string
            format: uuid
            description: 'Keyset cursor: the `next_before_id` from the previous page.'
          required: false
          description: 'Keyset cursor: the `next_before_id` from the previous page.'
          name: before_id
          in: query
        - schema:
            type: string
            minLength: 1
            description: Only payouts in this asset.
            example: USDC
          required: false
          description: Only payouts in this asset.
          name: asset
          in: query
        - schema:
            type: string
            enum:
              - received
              - validated
              - held
              - submitted
              - pending
              - succeeded
              - failed
              - reversed
            description: Only payouts in this status.
          required: false
          description: Only payouts in this status.
          name: status
          in: query
        - $ref: '#/components/parameters/HermesOrg'
      responses:
        '200':
          description: One page of payouts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutList'
        '400':
          description: Malformed `limit`, `before_id`, `asset` or `status`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing, malformed, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: >-
            Organization suspended, request IP not on the allowlist, or no
            multi-asset access yet (`onboarding_incomplete` /
            `access_suspended`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: The `/v2` shutter is closed — check `GET /v2/ping`.
          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:
    PayoutList:
      type: object
      properties:
        payouts:
          type: array
          items:
            $ref: '#/components/schemas/Payout'
        has_more:
          type: boolean
        next_before_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Pass back as `before_id` for the next page; null means done.
      required:
        - payouts
        - has_more
        - next_before_id
    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
    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
  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.