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

# Create a payout request



## OpenAPI

````yaml /openapi.json post /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:
    post:
      tags:
        - payouts
      summary: Create a payout request
      operationId: PayoutsController_createPayout
      parameters:
        - name: X-Request-Id
          in: header
          required: false
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            Unique idempotency token per logical write (UUID v4). Re-send the
            same value on safe retries.
          schema:
            type: string
            format: uuid
            example: a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePayoutDto'
      responses:
        '201':
          description: Payout created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponseDto'
        '403':
          description: Tenant not approved for payouts (KYC/KYB)
      security:
        - api-key: []
components:
  schemas:
    CreatePayoutDto:
      type: object
      properties:
        destination_type:
          type: string
          enum:
            - MOBILE_MONEY
            - BANK_ACCOUNT
            - CRYPTO_WALLET
          example: MOBILE_MONEY
        destination_country:
          type: string
          example: GH
          description: ISO 3166-1 alpha-2 country code
        settlement_currency:
          type: string
          example: USDT
          description: >-
            Currency the merchant settles in — USDT (crypto rail) or NGN (bank
            transfer). Defaults to USDT.
        settlement_network:
          type: string
          enum:
            - TRON
            - BSC
          example: TRON
          description: >-
            Crypto rail only: the chain the merchant will settle on (TRON or
            BSC). Selects which per-merchant receiving address the payment
            instruction shows. Ignored on the bank-transfer rail. Defaults to
            TRON for crypto settlements.
        destination_currency:
          type: string
          example: GHS
          description: ISO 4217 currency code
        destination_amount:
          type: number
          example: 500
          description: Amount the beneficiary receives
        destination_account_unique:
          type: string
          example: '0244000000'
          description: Mobile number or bank account number
        destination_provider_name:
          type: string
          example: MTN
          description: Mobile money provider or bank name
        destination_provider_code:
          type: string
          example: '044'
          description: >-
            Machine code for the destination institution — the bank code for
            BANK_ACCOUNT, the mobile money code for MOBILE_MONEY. Required for
            both: the processor routes on this code and never on the display
            name. Omit for CRYPTO_WALLET. Codes are corridor-specific — fetch
            them from the processor bank list.
        destination_account_name:
          type: string
          example: Kwame Mensah
          description: >-
            Beneficiary name. Required for BANK_ACCOUNT and MOBILE_MONEY — the
            processor rejects a transfer without it.
        merchant_reference:
          type: string
          example: ref_merchant_xyz_001
        notification_url:
          type: string
          example: https://merchant.example.com/hooks/this-payout
          description: >-
            Per-payout webhook override. When set, events for this payout are
            delivered here instead of the tenant default webhook URL.
      required:
        - destination_type
        - destination_country
        - destination_currency
        - destination_amount
        - destination_account_unique
        - destination_provider_name
    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

````