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

# List payouts

> Deprecated: use GET /v2/payouts for opaque cursor pagination.



## OpenAPI

````yaml /openapi.json get /v1/payouts
openapi: 3.0.0
info:
  contact: {}
  description: >-
    Comprehensive payment platform API supporting fiat and crypto payments,
    currency conversion, and compliance management
  title: Zuba Payment Platform API
  version: '1.0'
servers: []
security: []
tags:
  - description: Manage M2M API keys and credentials
    name: API Keys
  - description: Internal ledger accounts and transactions
    name: Ledger
  - description: Handle incoming payments and deposits
    name: Pay-ins
  - description: Manage payouts, beneficiaries, and SEPA transfers
    name: Payouts
  - description: Manage outbound webhook endpoints and deliveries
    name: Webhooks
paths:
  /v1/payouts:
    get:
      tags:
        - Payouts
      summary: List payouts
      description: 'Deprecated: use GET /v2/payouts for opaque cursor pagination.'
      operationId: PayoutController_listPayouts
      parameters:
        - description: Filter by beneficiary ID
          in: query
          name: beneficiaryId
          required: false
          schema:
            example: 123e4567-e89b-12d3-a456-426614174000
            format: uuid
            type: string
        - description: >-
            Return the payout created with this client reference (exact match).
            References are unique per workspace, so at most one payout matches;
            an empty list means no payout was ever created with this reference.
          in: query
          name: clientRef
          required: false
          schema:
            example: '1000000026117856401'
            maxLength: 100
            type: string
        - description: Filter by status (comma-separated)
          in: query
          name: status
          required: false
          schema:
            example: processing,paid
            type: string
        - description: Filter by country code (comma-separated)
          in: query
          name: country
          required: false
          schema:
            example: DE,GB
            type: string
        - description: Filter by payment route (comma-separated)
          in: query
          name: route
          required: false
          schema:
            example: sepa_inst,sepa_credit
            type: string
        - description: Filter by account holder name
          in: query
          name: provider
          required: false
          schema:
            example: Acme Ltd
            type: string
        - description: Start date for date range filter (ISO 8601)
          in: query
          name: startDate
          required: false
          schema:
            example: '2024-01-01T00:00:00Z'
            format: date-time
            type: string
        - description: End date for date range filter (ISO 8601)
          in: query
          name: endDate
          required: false
          schema:
            example: '2024-12-31T23:59:59Z'
            format: date-time
            type: string
        - description: >-
            Minimum amount filter (decimal string; the legacy numeric form is
            also accepted)
          in: query
          name: minAmount
          required: false
          schema:
            example: '100'
            type: string
        - description: >-
            Maximum amount filter (decimal string; the legacy numeric form is
            also accepted)
          in: query
          name: maxAmount
          required: false
          schema:
            example: '1000'
            type: string
        - description: 'Cursor for pagination (composite: timestamp__uuid)'
          in: query
          name: cursor
          required: false
          schema:
            example: 2024-01-15T10:30:00.000Z__a1b2c3d4-e5f6-7890-abcd-ef1234567890
            type: string
        - description: Number of items per page
          in: query
          name: limit
          required: false
          schema:
            default: 20
            example: 20
            maximum: 100
            minimum: 1
            type: number
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutListDto'
          description: List of payouts
        '400':
          description: Bad Request - Invalid query parameters
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      deprecated: true
      security:
        - bearer: []
components:
  schemas:
    PayoutListDto:
      properties:
        hasMore:
          description: Whether there are more payouts to load
          example: true
          type: boolean
        nextCursor:
          description: 'Next cursor for pagination (composite: timestamp__uuid)'
          example: 2024-01-15T10:30:00.000Z__a1b2c3d4-e5f6-7890-abcd-ef1234567890
          type: string
        payouts:
          description: List of payouts
          items:
            $ref: '#/components/schemas/PayoutDto'
          type: array
        total:
          description: >-
            Total number of payouts matching the query, ignoring pagination.
            Returned on the first page only (omitted on cursor pages).
          example: 1247
          type: number
      required:
        - payouts
        - hasMore
      type: object
    PayoutDto:
      properties:
        amount:
          description: >-
            Amount of the payout (as string to avoid floating-point precision
            issues)
          example: '100.50'
          type: string
        balanceAfter:
          description: >-
            Account balance after this transaction (in input currency, e.g.,
            EUR)
          example: '98.87'
          type: string
        beneficiary:
          allOf:
            - $ref: '#/components/schemas/BeneficiaryDto'
          description: Beneficiary information
          example:
            accounts:
              - createdAt: '2024-01-15T10:30:00Z'
                currency: EUR
                data:
                  bic: DEUTDEFF
                  iban: DE89370400440532013000
                id: 123e4567-e89b-12d3-a456-426614174000
                status: active
                type: iban
                updatedAt: '2024-01-15T10:35:00Z'
            createdAt: '2024-01-15T10:30:00Z'
            email: john.doe@example.com
            id: 123e4567-e89b-12d3-a456-426614174000
            name: John Doe
            status: active
            updatedAt: '2024-01-15T10:35:00Z'
        clientRef:
          description: >-
            Client-supplied idempotency reference provided at payout creation.
            Stable across retries and the natural lookup key for support /
            reconciliation. Absent on provider-synthesized DTOs (e.g. webhook
            callbacks) where the original client ref is not in scope.
          example: PAYOUT-REF-12345
          maxLength: 100
          type: string
        completedAt:
          description: Completion timestamp
          example: '2024-01-15T10:40:00Z'
          format: date-time
          type: string
        createdAt:
          description: Creation timestamp
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        currency:
          description: >-
            Currency code (ISO 4217). Default enabled currencies: EUR, USD, GBP,
            USDC, EURC, NGN. Contact your account manager to enable additional
            currencies.
          enum:
            - EUR
            - USD
            - GBP
            - USDC
            - USDT
            - EURC
            - NGN
            - XOF
            - XAF
            - GHS
          example: EUR
          type: string
        description:
          description: Description of the payout
          example: Payment for services rendered
          type: string
        failureCategory:
          description: Category of failure for client-facing display
          enum:
            - payment_not_approved
            - recipient_details
            - amount_issue
            - technical_error
          example: payment_not_approved
          type: string
        failureReason:
          description: Reason for failure if payout failed
          example: Insufficient funds
          type: string
        fee:
          description: >-
            Fee charged for the payout (as string to avoid floating-point
            precision issues)
          example: '2.50'
          type: string
        fxRate:
          description: >-
            FX rate applied (rate with markup charged to the client, e.g.,
            970.87 NGN per EUR)
          example: '970.87378641'
          type: string
        id:
          description: Unique identifier for the payout
          example: 123e4567-e89b-12d3-a456-426614174000
          format: uuid
          type: string
        inputAmount:
          description: >-
            Input amount (total amount charged to the client including fee, in
            input currency)
          example: '1.13'
          type: string
        inputCurrency:
          description: >-
            Input currency (the currency debited from the client account). This
            is determined by the inputCurrency provided in the request, or
            automatically selected as the currency with the largest available
            balance, or defaults to USD. For example, EUR when paying out NGN.
            Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact
            your account manager to enable additional currencies.
          enum:
            - EUR
            - USD
            - GBP
            - USDC
            - USDT
            - EURC
            - NGN
            - XOF
            - XAF
            - GHS
          example: EUR
          type: string
        payoutAccountData:
          additionalProperties: true
          description: Payout account data (JSONB)
          example:
            account: 123456789
            bankCode: '044'
            crAccount: '0123456789'
          type: object
        payoutAccountId:
          description: Payout account ID
          example: 123e4567-e89b-12d3-a456-426614174000
          format: uuid
          type: string
        processedAt:
          description: Processing start timestamp
          example: '2024-01-15T10:32:00Z'
          format: date-time
          type: string
        providerReference:
          description: Reference from the payment provider
          example: TXN123456789
          type: string
        reference:
          description: >-
            Optional free-text memo/narration that appears on the recipient
            side. Use clientRef for idempotency / support lookups.
          example: January invoice
          type: string
        route:
          description: >-
            Client-facing payment rail. Provider names are never exposed; a
            provider-routed transfer reads as a generic rail (e.g.
            `international`).
          example: international
          type: string
        status:
          description: Current status of the payout
          enum:
            - created
            - queued
            - processing
            - paid
            - failed
            - cancelled
          example: processing
          type: string
        txHash:
          description: >-
            On-chain transaction hash for crypto payouts, once the transfer is
            broadcast to the network. Null for non-crypto payouts or before
            broadcast.
          example: '0x3a1f9c2b4d5e6f70819a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70'
          nullable: true
          type: string
        type:
          description: Type of payout
          enum:
            - fiat
            - crypto
          example: fiat
          type: string
        uetr:
          description: >-
            SWIFT UETR (Unique End-to-end Transaction Reference) for SWIFT
            payouts, once the provider exposes it. Null otherwise.
          example: 4afd0a57-03af-4138-9341-373a78891ea9
          nullable: true
          type: string
        updatedAt:
          description: Last update timestamp
          example: '2024-01-15T10:35:00Z'
          format: date-time
          type: string
      required:
        - id
        - amount
        - currency
        - route
        - type
        - beneficiary
        - status
        - fee
        - createdAt
        - updatedAt
      type: object
    BeneficiaryDto:
      properties:
        accounts:
          description: Array of associated payment accounts
          items:
            $ref: '#/components/schemas/AccountDto'
          type: array
        address:
          description: Address line 1 of the beneficiary
          example: Hauptstraße 123
          type: string
        addressLine2:
          description: Address line 2 of the beneficiary
          example: Apt 4B, 3rd Floor
          type: string
        city:
          description: City of the beneficiary
          example: Berlin
          type: string
        country:
          description: Country code (ISO 3166-1 alpha-2)
          example: DE
          type: string
        countrySubdivision:
          description: Country subdivision code (e.g., US state code "NY", "CA")
          example: NY
          type: string
        createdAt:
          description: ISO timestamp when the beneficiary was created
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        dateOfBirth:
          description: Date of birth in YYYY-MM-DD format (individual beneficiaries only).
          example: '1985-05-20'
          type: string
        email:
          description: Email address of the beneficiary
          example: john.doe@example.com
          type: string
        id:
          description: Unique identifier for the beneficiary
          example: 123e4567-e89b-12d3-a456-426614174000
          format: uuid
          type: string
        middleName:
          description: Middle name of the beneficiary
          example: James
          type: string
        name:
          description: Full name of the beneficiary
          example: John Doe
          type: string
        notes:
          description: Notes about the beneficiary
          example: Regular client, prefers SEPA Instant
          type: string
        postcode:
          description: Postal code of the beneficiary
          example: '10115'
          type: string
        status:
          description: Beneficiary status
          enum:
            - active
            - inactive
            - suspended
          example: active
          type: string
        type:
          description: Beneficiary type
          enum:
            - individual
            - business
          example: individual
          type: string
        updatedAt:
          description: ISO timestamp when the beneficiary was last updated
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
      required:
        - id
        - name
        - type
        - country
        - accounts
        - status
        - createdAt
        - updatedAt
      type: object
    AccountDto:
      properties:
        createdAt:
          description: Creation timestamp
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        currency:
          description: >-
            Currency code (ISO 4217). Default enabled currencies: EUR, USD, GBP,
            USDC, EURC, NGN. Contact your account manager to enable additional
            currencies.
          enum:
            - EUR
            - USD
            - GBP
            - USDC
            - USDT
            - EURC
            - NGN
            - XOF
            - XAF
            - GHS
          example: EUR
          type: string
        data:
          additionalProperties: true
          description: Account data specific to the account type
          example:
            bic: DEUTDEFF
            iban: DE89370400440532013000
          type: object
        id:
          description: Unique identifier for the account
          example: 123e4567-e89b-12d3-a456-426614174000
          format: uuid
          type: string
        resolutionStatus:
          description: >-
            Resolution status of the account number against the bank (NGN bank
            accounts only).
          enum:
            - unresolved
            - resolved
            - invalid
          example: resolved
          type: string
        resolvedAccountName:
          description: >-
            Account-holder name returned by the bank when the account was
            resolved, if available.
          example: JANE DOE
          type: string
        status:
          description: Status of the account
          enum:
            - active
            - suspended
            - closed
          example: active
          type: string
        type:
          description: Type of payment account
          enum:
            - iban
            - card
            - bank_account
            - wallet
            - swift
            - mobile
          example: iban
          type: string
        updatedAt:
          description: Last update timestamp
          example: '2024-01-15T10:35:00Z'
          format: date-time
          type: string
      required:
        - id
        - type
        - currency
        - data
        - status
        - createdAt
        - updatedAt
      type: object
  securitySchemes:
    bearer:
      bearerFormat: JWT
      description: Enter Auth0 JWT token
      scheme: bearer
      type: http

````