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

# List payouts

> Cursor-paginated, newest first.



## OpenAPI

````yaml /openapi.json get /v1/payouts
openapi: 3.0.0
info:
  title: Spendin Merchant API
  description: Cross-border remittance and financial services API
  version: '1.0'
  contact: {}
servers:
  - url: https://api.spendin.app
    description: Production
security:
  - api-key: []
tags: []
paths:
  /v1/payouts:
    get:
      tags:
        - payouts
      summary: List payouts
      description: Cursor-paginated, newest first.
      operationId: PayoutsController_listPayouts
      parameters:
        - name: cursor
          required: false
          in: query
          description: Pagination cursor
          schema:
            type: string
        - name: limit
          required: false
          in: query
          description: Page size (1–100, default 20)
          schema:
            type: number
      responses:
        '200':
          description: Paginated payout list
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PayoutResponseDto'
                  meta:
                    $ref: '#/components/schemas/PaginationMetaDto'
      security:
        - api-key: []
components:
  schemas:
    PayoutResponseDto:
      type: object
      properties:
        id:
          type: string
          example: a3f1c2d4-...
        tenant_id:
          type: string
        status:
          type: string
          enum:
            - CREATED
            - PENDING_PAYMENT
            - PAYMENT_RECEIVED
            - PROCESSING
            - SUCCESSFUL
            - FAILED
            - EXPIRED
        merchant_reference:
          type: object
          nullable: true
        notification_url:
          type: object
          nullable: true
          description: Per-payout webhook override, if set
        destination_type:
          type: string
          enum:
            - MOBILE_MONEY
            - BANK_ACCOUNT
            - CRYPTO_WALLET
        destination_country:
          type: string
          example: GH
        destination_currency:
          type: string
          example: GHS
        destination_amount:
          type: number
          example: 500
        destination_account_unique:
          type: string
          example: '0244000000'
        destination_provider_name:
          type: string
          example: MTN
        destination_provider_code:
          type: object
          example: '044'
          nullable: true
          description: >-
            Bank code / mobile money code the processor routes on. Null for
            crypto.
        destination_account_name:
          type: object
          nullable: true
        settlement_currency:
          type: string
          example: USDT
        settlement_amount:
          type: number
          example: 28.5
          description: Set by generate-payment-instructions job
        exchange_rate:
          type: number
          example: 17.543
        platform_fee_amount:
          type: number
          example: 1.5
        platform_fee_currency:
          type: string
          example: USDT
        network_fee_amount:
          type: number
          example: 0.5
        network_fee_currency:
          type: string
          example: USDT
        total_fee_amount:
          type: number
          example: 2
        total_fee_currency:
          type: string
          example: USDT
        is_refunded:
          type: boolean
          example: false
        payment_instruction:
          description: >-
            Current active payment instruction, if generated (null until the
            cronjob runs)
          nullable: true
          allOf:
            - $ref: '#/components/schemas/PaymentInstructionSummaryDto'
        status_timeline:
          description: Status transition history, oldest → newest
          type: array
          items:
            $ref: '#/components/schemas/PayoutStatusLogDto'
        created_at:
          type: string
          example: '2026-03-06T14:30:00.000Z'
        updated_at:
          type: string
          example: '2026-03-06T14:30:01.000Z'
      required:
        - id
        - tenant_id
        - status
        - merchant_reference
        - notification_url
        - destination_type
        - destination_country
        - destination_currency
        - destination_amount
        - destination_account_unique
        - destination_provider_name
        - destination_provider_code
        - destination_account_name
        - settlement_currency
        - settlement_amount
        - exchange_rate
        - platform_fee_amount
        - platform_fee_currency
        - network_fee_amount
        - network_fee_currency
        - total_fee_amount
        - total_fee_currency
        - is_refunded
        - payment_instruction
        - status_timeline
        - created_at
        - updated_at
    PaginationMetaDto:
      type: object
      properties:
        next_cursor:
          type: object
          example: eyJpZCI6IjEyMyJ9
          nullable: true
        has_more:
          type: boolean
          example: true
        limit:
          type: number
          example: 20
      required:
        - next_cursor
        - has_more
        - limit
    PaymentInstructionSummaryDto:
      type: object
      properties:
        id:
          type: string
          example: b7e2f1a0-...
        rail:
          type: string
          enum:
            - CRYPTO
            - BANK_TRANSFER
          example: CRYPTO
        account_unique:
          type: string
          example: TXyz1234...abc
          description: Crypto address or virtual account number
        provider_name:
          type: string
          example: USDT (TRC-20)
        network:
          type: object
          example: TRC20
          nullable: true
        expected_amount:
          type: number
          example: 28.5
        expected_currency:
          type: string
          example: USDT
        payment_status:
          type: string
          enum:
            - UNPAID
            - PAID
            - EXPIRED
          example: UNPAID
        expires_at:
          type: string
          example: '2026-03-06T15:00:00.000Z'
        paid_at:
          type: object
          example: '2026-03-06T14:38:14.000Z'
          nullable: true
      required:
        - id
        - rail
        - account_unique
        - provider_name
        - network
        - expected_amount
        - expected_currency
        - payment_status
        - expires_at
        - paid_at
    PayoutStatusLogDto:
      type: object
      properties:
        from_status:
          type: string
          enum:
            - CREATED
            - PENDING_PAYMENT
            - PAYMENT_RECEIVED
            - PROCESSING
            - SUCCESSFUL
            - FAILED
            - EXPIRED
          nullable: true
        to_status:
          type: string
          enum:
            - CREATED
            - PENDING_PAYMENT
            - PAYMENT_RECEIVED
            - PROCESSING
            - SUCCESSFUL
            - FAILED
            - EXPIRED
        triggered_by:
          type: string
          enum:
            - SYSTEM
            - API
            - PROCESSOR_WEBHOOK
            - ADMIN
        reason_code:
          type: string
          example: PAYOUT_CREATED
        reason_detail:
          type: object
          nullable: true
        metadata:
          type: object
          nullable: true
        created_at:
          type: string
          example: '2026-03-06T14:30:00.000Z'
      required:
        - from_status
        - to_status
        - triggered_by
        - reason_code
        - reason_detail
        - metadata
        - created_at
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: X-API-Key

````