# List settlements

API to fetch first party payouts (settlements) with enhanced v1 response format.

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

## Query parameters:

  - `id` (string)
    Filter settlements by specific settlement ID

  - `type` (string)
    Settlement type
    Enum: "FIAT", "CRYPTO"

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

  - `since` (string)
    ISO 8601 timestamp after settlement was created

  - `until` (string)
    ISO 8601 timestamp before settlement was created

  - `page` (integer)
    Page number (zero-indexed, starts at 0)

  - `size` (integer)
    Number of settlements per page
    Example: 10

## Response 200 fields (application/json):

  - `content` (array)
    Example: [{"id":"63dd59dd-88be-41a2-a246-2f6724209422","source_account_id":"c3d4e5f6-a7b8-9012-cdef-234567890123","currency":"USD","gross_amount":"50.00","settlement_amount":"49.50","fees":{"transaction_fees":"0.50"},"status":"COMPLETED","data":{"transaction_reference_numbers":["ABC12345"],"payout_destination":{"type":"FEDWIRE","account_name":"Finance Corp","account_number":"XXXX7890","routing_number":"021000021","swift_code":"CHASUS33","institution_name":"Bank of America","reference":"INV-2024-001"}},"created_at":"2025-09-18T22:54:00.542Z","updated_at":"2025-09-18T22:54:00.542Z"}]

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

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

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

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

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

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

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

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

  - `content.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.

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

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

  - `content.data.payout_destination` (object, required)
    Configured payout destination for a settlement, discriminated by type (the payment rail).
Fiat settlements use FEDWIRE / ACH / RTP / PIX; crypto settlements use BLOCKCHAIN.

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

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

  - `page` (object)
    Pagination metadata.

  - `page.page` (integer, required)

  - `page.size` (integer, required)
    Example: 10

  - `page.total_elements` (integer, required)
    Example: 100

  - `page.total_pages` (integer, required)
    Example: 10

## Response 400 fields (application/json):

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

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