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

# Get a payout

> Includes the nested active payment instruction and the full status timeline — every transition with its reason code.



## OpenAPI

````yaml /openapi.json get /v1/payouts/{id}
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/{id}:
    get:
      tags:
        - payouts
      summary: Get a payout
      description: >-
        Includes the nested active payment instruction and the full status
        timeline — every transition with its reason code.
      operationId: PayoutsController_getPayout
      parameters:
        - name: id
          required: true
          in: path
          schema:
            format: uuid
            type: string
      responses:
        '200':
          description: Payout found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponseDto'
        '404':
          description: Payout not found
      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
    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

````