# Create a settlement

API to initiate a first party payout (settlement to our customer).

Endpoint: POST /v1/collections/settlements
Version: 1.0.0
Security: Bearer

## Request fields (application/json):

  - `source_account_id` (string, required)
    Source account to draw funds from. Must be CUSTOMER-owned and ACTIVE.
    Example: "b2c3d4e5-f6a7-8901-bcde-f12345678901"

## Response 201 fields (application/json):

  - `id` (string, required)
    Unique identifier for the settlement
    Example: "63dd59dd-88be-41a2-a246-2f6724209422"

  - `source_account_id` (string, required)
    Source account the settlement was drawn from
    Example: "c3d4e5f6-a7b8-9012-cdef-234567890123"

  - `currency` (string, required)
    Currency code for the settlement
    Example: "USD"

  - `gross_amount` (string, required)
    Total settlement amount before fees
    Example: "50.00"

  - `settlement_amount` (string, required)
    Net settlement amount after fees
    Example: "49.50"

  - `fees` (object, required)
    Fees applied to the settlement
    Example: {"transaction_fees":"0.50"}

  - `fees.transaction_fees` (string, required)
    Total transaction fees applied to the settlement, as a string to preserve precision
    Example: "0.50"

  - `status` (string, required)
    Settlement status
    Enum: "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED"

  - `data` (object, required)
    Settlement execution data — carries the bank transaction reference numbers (fiat) or the on-chain transaction hash (crypto), plus the configured payout destination.

  - `data.transaction_reference_numbers` (array)
    Bank transaction reference numbers; populated for fiat settlements after completion
    Example: ["ABC12345"]

  - `data.transaction_hash` (string)
    On-chain transaction hash; populated for crypto settlements after completion
    Example: "0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF"

  - `data.payout_destination` (object, required) — one of (discriminator: type):
    Configured payout destination for a settlement, discriminated by type (the payment rail).
Fiat settlements use FEDWIRE / ACH / RTP / PIX; crypto settlements use BLOCKCHAIN.
    - BLOCKCHAIN:
      - `type` (string, required)
        Discriminator: indicates blockchain payout
        Enum: "BLOCKCHAIN"
      - `network` (string, required)
        Supported blockchain networks
        Enum: "ETHEREUM", "ETHEREUM_SEPOLIA_TESTNET", "SOLANA", "SOLANA_TESTNET", "XRPL", "XRPL_TESTNET"
      - `address` (string, required)
        Destination blockchain wallet address
        Example: "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh"
      - `currency` (string)
        Cryptocurrency asset symbol
        Example: "RLUSD"
      - `destination_tag` (string)
        Optional destination tag/memo for networks that require one (e.g. XRPL)
        Example: "12345"
    - FEDWIRE:
      - `type` (string, required)
        Discriminator: indicates Fedwire payout
        Enum: "FEDWIRE"
      - `account_name` (string)
        Name on the destination bank account (the Ripple customer receiving the settlement)
        Example: "Finance Corp"
      - `account_number` (string, required)
        Destination bank account number (obfuscated; only the last four digits are shown)
        Example: "XXXX7890"
      - `routing_number` (string, required)
        ABA routing number
        Example: "021000021"
      - `swift_code` (string)
        SWIFT/BIC code for international payouts
        Example: "CHASUS33"
      - `institution_name` (string)
        Name of the receiving financial institution
        Example: "Bank of America"
      - `reference` (string)
        Reference to include with the payout
        Example: "INV-2024-001"
    - ACH:
      - `type` (string, required)
        Discriminator: indicates ACH payout
        Enum: "ACH"
      - `account_name` (string)
        Name on the destination bank account (the Ripple customer receiving the settlement)
        Example: "Finance Corp"
      - `account_number` (string, required)
        Destination bank account number (obfuscated; only the last four digits are shown)
        Example: "XXXX7890"
      - `routing_number` (string, required)
        ABA routing number
        Example: "021000021"
      - `institution_name` (string)
        Name of the receiving financial institution
        Example: "Bank of America"
      - `reference` (string)
        Reference to include with the payout
        Example: "INV-2024-001"
    - RTP:
      - `type` (string, required)
        Discriminator: indicates RTP payout
        Enum: "RTP"
      - `account_name` (string)
        Name on the destination bank account (the Ripple customer receiving the settlement)
        Example: "Finance Corp"
      - `account_number` (string, required)
        Destination bank account number (obfuscated; only the last four digits are shown)
        Example: "XXXX7890"
      - `routing_number` (string, required)
        ABA routing number
        Example: "021000021"
      - `institution_name` (string)
        Name of the receiving financial institution
        Example: "Bank of America"
      - `reference` (string)
        Reference to include with the payout
        Example: "INV-2024-001"
    - PIX:
      - `type` (string, required)
        Discriminator: indicates PIX payout
        Enum: "PIX"
      - `pix_key` (string, required)
        PIX key for the payout (obfuscated; only the last four characters are shown)
        Example: "XXXX8901"
      - `pix_key_type` (string, required)
        Type of PIX key
        Enum: "CPF", "CNPJ", "EMAIL", "PHONE", "RANDOM"
      - `beneficiary_name` (string)
        Name of the account holder as registered with PIX (the Ripple customer receiving the settlement)
        Example: "Finance Corp"

  - `created_at` (string, required)
    ISO 8601 timestamp when the settlement was created
    Example: "2025-09-18T22:54:00.542Z"

  - `updated_at` (string, required)
    ISO 8601 timestamp when the settlement was last updated
    Example: "2025-09-18T22:54:00.542Z"

## Response 400 fields (application/json):

  - `code` (string, required)
    Error code identifying the type of error

  - `reason` (string, required)
    Human-readable error message