> ## Documentation Index > Fetch the complete documentation index at: https://docs.superbank.co/llms.txt > Use this file to discover all available pages before exploring further. # Create a settlement request ## OpenAPI ````yaml /openapi/v0/openapi.json post /v0/settlement-requests openapi: 3.0.0 info: title: Superbank API description: Superbank Developer API for Instant Settlement version: '1.0' contact: {} servers: - url: https://api-sandbox.superbank.co description: Sandbox security: [] tags: [] paths: /v0/settlement-requests: post: tags: - Settlement Requests summary: Create a settlement request operationId: SettlementRequestsController_create parameters: - name: Idempotency-Key in: header description: >- Optional Stripe-style idempotency key. Same key + body within 24h replays the cached response. Same key + different body returns 400 idempotency_mismatch. Concurrent same-key requests return 409 idempotency_conflict. Scope is per API key. required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateInstantSettlementDto' responses: '201': description: Settlement request created with status OPEN content: application/json: schema: $ref: '#/components/schemas/SettlementRequestResponseDto' '400': description: Bad request '401': description: Unauthorized '409': description: Idempotency conflict (in-flight) security: - api-key: [] components: schemas: CreateInstantSettlementDto: type: object properties: type: type: string description: The type of settlement request example: FIAT_TO_STABLECOIN enum: - STABLECOIN_TO_STABLECOIN - FIAT_TO_STABLECOIN - STABLECOIN_TO_FIAT - FIAT_TO_FIAT payment_reason: type: string description: >- Regulatory categorisation of the payment. Not visible to the recipient. The full enum mirrors the upstream regulatory taxonomy and is intentionally broad — most fintech integrations only need a small subset. Common values for fintech use cases: `REMITTANCES` (cross-border consumer transfers), `PAYMENT_FOR_GOODS_AND_SERVICES` (merchant payments), `EMPLOYEE_SALARIES_OR_WAGES` (payroll)Use `OTHER` only as a last resort — pick the closest specific value where possible. example: REMITTANCES enum: - CAPITAL_CONTRIBUTIONS - CHARITABLE_CONTRIBUTIONS - CONSULTING_FEES - CORPORATE_TAX_PAYMENTS - DOWN_PAYMENTS_FOR_REAL_ESTATE - EDUCATION_FEES - EMPLOYEE_SALARIES_OR_WAGES - EXPENSES_REIMBURSEMENT - GIFTS - GOVERNMENT_GRANTS - INCOME_TAX_PAYMENTS - INHERITANCE_PAYMENTS - INSURANCE_CLAIM_PAYOUTS - INSURANCE_PREMIUM_PAYMENTS - INVESTMENTS - LOAN_ADVANCES - MORTGAGE_PAYMENTS - OTHER - PAYMENT_FOR_GOODS_AND_SERVICES - PERSONAL_TRANSFERS - REAL_ESTATE_PURCHASES - REMITTANCES - RENT - REPAYMENT_OF_LOANS - ROYALTIES - TRUST_FUND_DISTRIBUTIONS - UTILITY_BILLS - WELFARE_OR_BENEFITS - WINNINGS_AND_PRIZES amount: type: number description: >- The amount to be settled. Required for STABLECOIN_TO_STABLECOIN and FIAT_TO_STABLECOIN. For STABLECOIN_TO_FIAT, set the amount on `destination.amount` instead — the source crypto amount is computed based on the result from quote endpoint. example: 99 minimum: 0.01 source: description: >- The source of funds. Required for STABLECOIN_TO_FIAT (crypto rail + wallet address) and FIAT_TO_STABLECOIN (fiat rail + country code). Discriminated by rail: crypto rails use `wallet_address`; fiat rails use `country_code` (ISO 3166-1 alpha-2). oneOf: - title: Crypto allOf: - $ref: '#/components/schemas/CryptoSourceDto' - title: Fiat allOf: - $ref: '#/components/schemas/FiatSourceDto' discriminator: propertyName: rail mapping: SOLANA: $ref: '#/components/schemas/CryptoSourceDto' ETHEREUM: $ref: '#/components/schemas/CryptoSourceDto' BASE: $ref: '#/components/schemas/CryptoSourceDto' POLYGON: $ref: '#/components/schemas/CryptoSourceDto' TRON: $ref: '#/components/schemas/CryptoSourceDto' ARBITRUM: $ref: '#/components/schemas/CryptoSourceDto' ACH: $ref: '#/components/schemas/FiatSourceDto' RTP: $ref: '#/components/schemas/FiatSourceDto' DOMESTIC_WIRE: $ref: '#/components/schemas/FiatSourceDto' LOCAL: $ref: '#/components/schemas/FiatSourceDto' destination: description: >- The destination where the settlement funds will be sent. The required fields depend on the bank-identifier shape Walapay needs for the destination currency (the tabs below): - **Crypto** — `wallet_address`. - **US bank (ABA)** — USD via `ACH`/`RTP`/`DOMESTIC_WIRE`: `bank_name`, `account_number`, `routing_number`, `account_type`. - **IBAN** — EUR & GBP via `LOCAL`: `iban` (+ optional `bic`, and `sort_code` for GBP). - **CLABE** — MXN via `LOCAL`: `clabe`. - **Account + bank code** — NGN via `LOCAL`: `account_number`, `bank_code`. oneOf: - title: Crypto allOf: - $ref: '#/components/schemas/CryptoDestinationDto' - title: US bank (ABA) allOf: - $ref: '#/components/schemas/UsBankDestinationDto' - title: IBAN (EUR/GBP + EU/ME locals) allOf: - $ref: '#/components/schemas/IbanDestinationDto' - title: CLABE (Mexico) allOf: - $ref: '#/components/schemas/ClabeDestinationDto' - title: Account + bank code (Nigeria) allOf: - $ref: '#/components/schemas/AccountBankCodeDestinationDto' - title: Local account (LATAM) allOf: - $ref: '#/components/schemas/LocalAccountDestinationDto' - title: Specialized (IFSC / BSB / CNAPS / branch) allOf: - $ref: '#/components/schemas/SpecializedAccountDestinationDto' discriminator: propertyName: currency mapping: USDC: $ref: '#/components/schemas/CryptoDestinationDto' USDT: $ref: '#/components/schemas/CryptoDestinationDto' EURC: $ref: '#/components/schemas/CryptoDestinationDto' USD: $ref: '#/components/schemas/UsBankDestinationDto' CAD: $ref: '#/components/schemas/UsBankDestinationDto' EUR: $ref: '#/components/schemas/IbanDestinationDto' GBP: $ref: '#/components/schemas/IbanDestinationDto' PLN: $ref: '#/components/schemas/IbanDestinationDto' NOK: $ref: '#/components/schemas/IbanDestinationDto' DKK: $ref: '#/components/schemas/IbanDestinationDto' AED: $ref: '#/components/schemas/IbanDestinationDto' SEK: $ref: '#/components/schemas/IbanDestinationDto' TRY: $ref: '#/components/schemas/IbanDestinationDto' ILS: $ref: '#/components/schemas/IbanDestinationDto' SAR: $ref: '#/components/schemas/IbanDestinationDto' EGP: $ref: '#/components/schemas/IbanDestinationDto' CRC: $ref: '#/components/schemas/IbanDestinationDto' MXN: $ref: '#/components/schemas/ClabeDestinationDto' NGN: $ref: '#/components/schemas/AccountBankCodeDestinationDto' GTQ: $ref: '#/components/schemas/LocalAccountDestinationDto' HNL: $ref: '#/components/schemas/LocalAccountDestinationDto' ARS: $ref: '#/components/schemas/LocalAccountDestinationDto' PEN: $ref: '#/components/schemas/LocalAccountDestinationDto' BOB: $ref: '#/components/schemas/LocalAccountDestinationDto' CLP: $ref: '#/components/schemas/LocalAccountDestinationDto' COP: $ref: '#/components/schemas/LocalAccountDestinationDto' GHS: $ref: '#/components/schemas/AccountBankCodeDestinationDto' KES: $ref: '#/components/schemas/AccountBankCodeDestinationDto' ZAR: $ref: '#/components/schemas/AccountBankCodeDestinationDto' IDR: $ref: '#/components/schemas/AccountBankCodeDestinationDto' VND: $ref: '#/components/schemas/AccountBankCodeDestinationDto' PHP: $ref: '#/components/schemas/AccountBankCodeDestinationDto' THB: $ref: '#/components/schemas/AccountBankCodeDestinationDto' MYR: $ref: '#/components/schemas/AccountBankCodeDestinationDto' KRW: $ref: '#/components/schemas/AccountBankCodeDestinationDto' BDT: $ref: '#/components/schemas/AccountBankCodeDestinationDto' PKR: $ref: '#/components/schemas/AccountBankCodeDestinationDto' LKR: $ref: '#/components/schemas/AccountBankCodeDestinationDto' SGD: $ref: '#/components/schemas/AccountBankCodeDestinationDto' JPY: $ref: '#/components/schemas/AccountBankCodeDestinationDto' INR: $ref: '#/components/schemas/SpecializedAccountDestinationDto' AUD: $ref: '#/components/schemas/SpecializedAccountDestinationDto' CNY: $ref: '#/components/schemas/SpecializedAccountDestinationDto' BRL: $ref: '#/components/schemas/SpecializedAccountDestinationDto' HKD: $ref: '#/components/schemas/LocalAccountDestinationDto' external_id: type: string description: >- An identifier of your choice for this settlement (e.g. your internal order id). Echoed back on every read and webhook. Filterable via `GET /v0/settlement-requests?external_id=...`. example: order_abc123 maxLength: 255 metadata: type: object description: >- Free-form key/value pairs for correlating this settlement with your own systems. Up to 50 keys. Keys may be up to 40 characters; values up to 500 characters. All values must be strings. Echoed back on every read and webhook; not filterable. example: restaurant_id: rest_42 source: web additionalProperties: type: string reconciliation_expected_at: type: string description: >- Override the expected reconciliation time (ISO 8601). The default is T+3 for all rails. Supply this field if you know your processor's value. Must be in the future and at most 30 days out from creation. If omitted, the default is applied at FUNDS_SENT transition time. example: '2026-05-04T17:00:00Z' required: - type - payment_reason - destination SettlementRequestResponseDto: type: object properties: id: type: string description: The unique identifier of the settlement request example: d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f8a type: type: string description: The type of settlement request example: FIAT_TO_STABLECOIN enum: - STABLECOIN_TO_STABLECOIN - FIAT_TO_STABLECOIN - STABLECOIN_TO_FIAT - FIAT_TO_FIAT payment_reason: type: string description: Reason for the payment; internal for the sender enum: - CAPITAL_CONTRIBUTIONS - CHARITABLE_CONTRIBUTIONS - CONSULTING_FEES - CORPORATE_TAX_PAYMENTS - DOWN_PAYMENTS_FOR_REAL_ESTATE - EDUCATION_FEES - EMPLOYEE_SALARIES_OR_WAGES - EXPENSES_REIMBURSEMENT - GIFTS - GOVERNMENT_GRANTS - INCOME_TAX_PAYMENTS - INHERITANCE_PAYMENTS - INSURANCE_CLAIM_PAYOUTS - INSURANCE_PREMIUM_PAYMENTS - INVESTMENTS - LOAN_ADVANCES - MORTGAGE_PAYMENTS - OTHER - PAYMENT_FOR_GOODS_AND_SERVICES - PERSONAL_TRANSFERS - REAL_ESTATE_PURCHASES - REMITTANCES - RENT - REPAYMENT_OF_LOANS - ROYALTIES - TRUST_FUND_DISTRIBUTIONS - UTILITY_BILLS - WELFARE_OR_BENEFITS - WINNINGS_AND_PRIZES example: REMITTANCES status: type: string description: The current lifecycle status of the settlement request enum: - REQUEST_STARTED - REQUEST_EXPIRED - REQUEST_CANCELED - REQUEST_COMPLETED - REQUEST_REFUNDED - FUNDS_SENT - FUNDS_RECEIVING_LATE - SETTLEMENT_SENT - SETTLEMENT_COMPLETED - PAYIN_CANCELED - PAYIN_UNDER_REVIEW - PAYIN_FAILED - PAYIN_AMOUNT_MISMATCH - PAYOUT_CANCELED - PAYOUT_UNDER_REVIEW - PAYOUT_FAILED example: REQUEST_STARTED amount: type: string description: The amount of the settlement request example: '99.00' external_id: type: object description: >- An identifier you supplied for this settlement (e.g. your internal order id). Filterable via `GET /v0/settlement-requests?external_id=...`. example: order_abc123 nullable: true metadata: type: object description: >- Free-form key/value pairs you supplied for correlation. Up to 50 string keys (≤40 chars) with string values (≤500 chars). Echoed on every read and webhook; not filterable. example: restaurant_id: rest_42 source: web additionalProperties: type: string nullable: true transaction_id: type: object deprecated: true description: >- **Deprecated — removal: 2026-05-25.** Use `external_id`. Same value, kept for compatibility until the removal date. example: your_trx_123 nullable: true source: description: The source details (for off-ramp) nullable: true type: object allOf: - $ref: '#/components/schemas/SourceResponseDto' destination: type: object description: The destination details for the settlement payment_instructions: description: Instructions describing the inbound payment allOf: - $ref: '#/components/schemas/PaymentInstructionsResponseDto' outbound_payment: description: The outbound payment from the pre-funded wallet to the destination nullable: true type: object allOf: - $ref: '#/components/schemas/PaymentSummaryResponseDto' inbound_payment: description: The inbound payment received from an external source nullable: true type: object allOf: - $ref: '#/components/schemas/PaymentSummaryResponseDto' created_at: type: string description: The timestamp when the settlement request was created example: '2026-01-20T15:17:12.805Z' updated_at: type: string description: The timestamp of the most recent update example: '2026-01-20T15:20:00.000Z' processing_at: type: object description: The timestamp when processing began example: '2026-01-20T15:20:00.000Z' nullable: true completed_at: type: object description: The timestamp when completed example: '2026-01-20T15:25:00.000Z' nullable: true reconciliation_expected_at: type: object description: The timestamp when funds are expected to reconcile example: '2026-01-23T15:20:00.000Z' nullable: true failure_code: type: string description: Structured failure code for programmatic handling enum: - AMOUNT_MISMATCH_UNDERPAYMENT - AMOUNT_MISMATCH_OVERPAYMENT example: AMOUNT_MISMATCH_UNDERPAYMENT nullable: true failure_reason: type: object description: Human-readable failure reason example: 'Amount mismatch: expected 100.00, received 90.00' nullable: true required: - id - type - payment_reason - status - amount - destination - payment_instructions - created_at - updated_at CryptoSourceDto: type: object properties: currency: type: string description: The source currency (USDC or USDT) example: USDC enum: - USDC - USDT rail: type: string description: The crypto rail the source funds arrive on example: SOLANA enum: - SOLANA - ETHEREUM - BASE - POLYGON - TRON - ARBITRUM wallet_address: type: string description: The wallet address of the source (end-user wallet) example: '0x388C818CA8B9251b393131C08a736A67ccB19297' required: - currency - rail - wallet_address FiatSourceDto: type: object properties: currency: type: string description: The fiat source currency code (ISO 4217) example: USD rail: type: string description: The fiat rail the end-user will deposit on example: ACH enum: - ACH - RTP - DOMESTIC_WIRE - LOCAL country_code: type: string description: >- ISO 3166-1 alpha-2 country code of the end-user's deposit (e.g. 'US', 'NG') example: US required: - currency - rail - country_code CryptoDestinationDto: type: object properties: is_third_party: type: boolean description: >- Whether the destination beneficiary is a third party relative to your business. - `true` — the beneficiary is *not* your registered company (e.g., a payout to a vendor, contractor, employee, or end-user). The processor will treat this as a third-party transfer and apply the corresponding compliance checks. - `false` — the beneficiary is your own company / registered account. example: true rail: type: string description: The crypto payment rail enum: - SOLANA - ETHEREUM - BASE - POLYGON - TRON - ARBITRUM example: SOLANA currency: type: string description: The crypto currency example: USDC wallet_address: type: string description: The wallet address that will receive the settlement funds example: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU beneficiary: description: The beneficiary that owns the destination wallet address allOf: - $ref: '#/components/schemas/BeneficiaryDto' required: - is_third_party - rail - currency - wallet_address - beneficiary UsBankDestinationDto: type: object properties: is_third_party: type: boolean description: >- Whether the destination beneficiary is a third party relative to your business. - `true` — the beneficiary is *not* your registered company (e.g., a payout to a vendor, contractor, employee, or end-user). The processor will treat this as a third-party transfer and apply the corresponding compliance checks. - `false` — the beneficiary is your own company / registered account. example: true amount: type: number description: >- The amount to deliver to the destination bank account, in the destination currency. The source crypto amount is computed. example: 1000 minimum: 0.01 country_code: type: string description: >- ISO 3166-1 alpha-2 country code of the destination (e.g. `US`, `CA`). Required for any fiat destination. example: US rail: type: string description: US fiat routing rail enum: - ACH - RTP - DOMESTIC_WIRE example: ACH currency: type: string description: Destination currency (ISO 4217) example: USD bank_name: type: string description: Bank name example: U.S. Bank account_number: type: string description: Bank account number example: '123456789' routing_number: type: string description: ABA routing number (9 digits) example: '021000021' account_type: type: string description: Account type enum: - CHECKING - SAVINGS example: CHECKING beneficiary: description: The beneficiary that owns the bank account allOf: - $ref: '#/components/schemas/BeneficiaryDto' required: - is_third_party - amount - country_code - rail - currency - bank_name - account_number - routing_number - account_type - beneficiary IbanDestinationDto: type: object properties: is_third_party: type: boolean description: >- Whether the destination beneficiary is a third party relative to your business. - `true` — the beneficiary is *not* your registered company (e.g., a payout to a vendor, contractor, employee, or end-user). The processor will treat this as a third-party transfer and apply the corresponding compliance checks. - `false` — the beneficiary is your own company / registered account. example: true amount: type: number description: >- The amount to deliver to the destination bank account, in the destination currency. The source crypto amount is computed. example: 1000 minimum: 0.01 country_code: type: string description: >- ISO 3166-1 alpha-2 country code of the destination (e.g. `US`, `CA`). Required for any fiat destination. example: US rail: type: string description: Routing rail — LOCAL for SEPA/Faster Payments example: LOCAL currency: type: string description: Destination currency — an IBAN corridor enum: - EUR - GBP - PLN - NOK - DKK - AED - SEK - TRY - ILS - SAR - EGP example: GBP iban: type: string description: IBAN of the receiving account example: GB29NWBK60161331926819 bank_code: type: string description: Clearing/bank code — required for SEK (Sweden) example: '8000' bank_name: type: string description: >- Bank name — required for TRY/ILS/SAR/EGP and must match the local bank directory (e.g. "AL INMA BANK" for SAR) example: AL INMA BANK bic: type: string description: BIC / SWIFT code example: NWBKGB2L sort_code: type: string description: UK sort code (6 digits) — GBP / Faster Payments example: '601613' account_type: type: string description: Account type (defaults CHECKING) enum: - CHECKING - SAVINGS example: CHECKING beneficiary: description: The beneficiary that owns the bank account allOf: - $ref: '#/components/schemas/BeneficiaryDto' required: - is_third_party - amount - country_code - rail - currency - iban - beneficiary ClabeDestinationDto: type: object properties: is_third_party: type: boolean description: >- Whether the destination beneficiary is a third party relative to your business. - `true` — the beneficiary is *not* your registered company (e.g., a payout to a vendor, contractor, employee, or end-user). The processor will treat this as a third-party transfer and apply the corresponding compliance checks. - `false` — the beneficiary is your own company / registered account. example: true amount: type: number description: >- The amount to deliver to the destination bank account, in the destination currency. The source crypto amount is computed. example: 1000 minimum: 0.01 country_code: type: string description: >- ISO 3166-1 alpha-2 country code of the destination (e.g. `US`, `CA`). Required for any fiat destination. example: US rail: type: string description: Routing rail — LOCAL for SPEI example: LOCAL currency: type: string description: Destination currency example: MXN clabe: type: string description: 18-digit CLABE example: '032180000118359719' beneficiary: description: The beneficiary that owns the bank account allOf: - $ref: '#/components/schemas/BeneficiaryDto' required: - is_third_party - amount - country_code - rail - currency - clabe - beneficiary AccountBankCodeDestinationDto: type: object properties: is_third_party: type: boolean description: >- Whether the destination beneficiary is a third party relative to your business. - `true` — the beneficiary is *not* your registered company (e.g., a payout to a vendor, contractor, employee, or end-user). The processor will treat this as a third-party transfer and apply the corresponding compliance checks. - `false` — the beneficiary is your own company / registered account. example: true amount: type: number description: >- The amount to deliver to the destination bank account, in the destination currency. The source crypto amount is computed. example: 1000 minimum: 0.01 country_code: type: string description: >- ISO 3166-1 alpha-2 country code of the destination (e.g. `US`, `CA`). Required for any fiat destination. example: US rail: type: string description: Routing rail — LOCAL example: LOCAL currency: type: string description: Destination currency enum: - NGN - GHS - KES - ZAR - IDR - VND - PHP - THB - MYR - KRW - BDT - PKR - LKR - SGD example: KES account_number: type: string description: Bank account number (NUBAN for NGN) example: '0123456789' bank_code: type: string description: Local bank code example: '058' bank_name: type: string description: >- Bank name — required for most corridors (not BDT/PKR) and must match the local bank directory (e.g. "Kenya Commercial Bank Limited" for KES) example: Kenya Commercial Bank Limited beneficiary: description: The beneficiary that owns the bank account allOf: - $ref: '#/components/schemas/BeneficiaryDto' required: - is_third_party - amount - country_code - rail - currency - account_number - bank_code - beneficiary LocalAccountDestinationDto: type: object properties: is_third_party: type: boolean description: >- Whether the destination beneficiary is a third party relative to your business. - `true` — the beneficiary is *not* your registered company (e.g., a payout to a vendor, contractor, employee, or end-user). The processor will treat this as a third-party transfer and apply the corresponding compliance checks. - `false` — the beneficiary is your own company / registered account. example: true amount: type: number description: >- The amount to deliver to the destination bank account, in the destination currency. The source crypto amount is computed. example: 1000 minimum: 0.01 country_code: type: string description: >- ISO 3166-1 alpha-2 country code of the destination (e.g. `US`, `CA`). Required for any fiat destination. example: US rail: type: string description: Routing rail — LOCAL example: LOCAL currency: type: string description: Destination currency enum: - GTQ - HNL - ARS - PEN - BOB - CLP - COP - USD example: COP account_number: type: string description: Local bank account number example: '000123456789' bank_name: type: string description: >- Bank name — required for PEN/BOB/CLP/COP and USD@Ecuador, and must match the local bank directory (e.g. "Banco de Bogota" for COP) example: Banco de Bogota bank_code: type: string description: Local bank/branch code, where applicable example: '007' account_type: type: string description: Account type (defaults CHECKING) enum: - CHECKING - SAVINGS example: CHECKING beneficiary: description: The beneficiary that owns the bank account allOf: - $ref: '#/components/schemas/BeneficiaryDto' required: - is_third_party - amount - country_code - rail - currency - account_number - beneficiary SpecializedAccountDestinationDto: type: object properties: is_third_party: type: boolean description: >- Whether the destination beneficiary is a third party relative to your business. - `true` — the beneficiary is *not* your registered company (e.g., a payout to a vendor, contractor, employee, or end-user). The processor will treat this as a third-party transfer and apply the corresponding compliance checks. - `false` — the beneficiary is your own company / registered account. example: true amount: type: number description: >- The amount to deliver to the destination bank account, in the destination currency. The source crypto amount is computed. example: 1000 minimum: 0.01 country_code: type: string description: >- ISO 3166-1 alpha-2 country code of the destination (e.g. `US`, `CA`). Required for any fiat destination. example: US rail: type: string description: Routing rail — LOCAL example: LOCAL currency: type: string description: Destination currency enum: - INR - AUD - CNY - BRL example: INR account_number: type: string description: Bank account number example: '000123456789' ifsc_code: type: string description: IFSC code — required for INR example: HDFC0001234 bsb_number: type: string description: BSB number — required for AUD example: '062000' cnaps_code: type: string description: CNAPS code — required for CNY example: '102100099996' branch_code: type: string description: Branch/agency code — required for BRL example: '0001' bank_name: type: string description: Bank name — required (directory-validated) for BRL example: BANCO DO BRASIL S.A beneficiary: description: The beneficiary that owns the bank account allOf: - $ref: '#/components/schemas/BeneficiaryDto' required: - is_third_party - amount - country_code - rail - currency - account_number - beneficiary SourceResponseDto: type: object properties: currency: type: string description: The currency of the source funds example: USDC rail: type: string description: The payment rail of the source example: SOLANA wallet_address: type: string description: The wallet address of the source (end-user wallet) example: '0x388C818CA8B9251b393131C08a736A67ccB19297' required: - currency - rail - wallet_address PaymentInstructionsResponseDto: type: object properties: amount: type: string description: >- The amount to send for the inbound payment. For STABLECOIN_TO_FIAT this is the exact crypto amount the end-user must deposit (computed from the destination amount plus fees). example: '729.16' currency: type: string description: The currency of the inbound payment (e.g. USDC, USDT, USD) example: USDC rail: type: string description: The rail of the inbound payment (e.g. SOLANA, TRON, RTP) example: SOLANA wallet_address: type: string description: >- The wallet address for crypto funding. For STABLECOIN_TO_FIAT this is a per-payment deposit wallet — send `amount` of `currency` here. Valid until `valid_until`. example: FRNthe6oqA8fhVMfXMM12rGmFYvejtkmH3bRfYBxWnLB chain: type: string description: The blockchain network for crypto funding example: SOLANA bank_name: type: string description: The bank name for fiat funding (for on-ramp with SUPERBANK) example: JPMorgan Chase account_number: type: string description: The account number for fiat funding example: '123456789' routing_number: type: string description: The routing number for fiat funding example: '021000021' deposit_message: type: string description: >- The deposit message / reference the end-user must include on the bank transfer so the deposit can be matched to this settlement. Missing or altered messages may cause the deposit to be returned. example: SB-39760060 valid_until: type: string description: The timestamp until which the payment instructions remain valid example: '2026-01-20T15:22:12.805Z' destination_amount: type: string description: >- STABLECOIN_TO_FIAT only — the amount delivered to the destination bank account in `destination_currency`. Echoes the requested amount. example: '1000.00' destination_currency: type: string description: STABLECOIN_TO_FIAT only — destination fiat currency example: CAD exchange_rate: type: string description: >- STABLECOIN_TO_FIAT only — locked mid-market rate (destination units per one source unit). example: '1.3788512205' fee: type: object description: >- Combined fee for this settlement. `fixed` is denominated in `currency` (e.g. USDC). `variable` is a fraction (0.005 = 0.5%). `total` is the absolute fee actually charged in `currency` — the cent-rounded figure that reconciles with the deposit amount. example: fixed: 1 variable: 0.005 total: 6 required: - currency - rail - valid_until PaymentSummaryResponseDto: type: object properties: id: type: string description: The unique identifier of the payment example: d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f8a type: type: string description: The type of payment enum: - PAYIN - PAYOUT example: PAYOUT status: type: string description: The status of the payment enum: - AWAITING_FUNDS - EXPIRED - PENDING - PROCESSING - SENT - COMPLETED - CANCELLED - FAILED - REFUNDED - SCHEDULED - UNDER_REVIEW example: PROCESSING amount: type: string description: The amount of the payment example: '99.00' currency: type: string description: The currency of the payment example: USDC created_at: type: string description: The timestamp when the payment was created example: '2026-01-20T15:20:00.000Z' required: - id - type - status - amount - currency - created_at BeneficiaryDto: type: object properties: type: type: string description: >- The type of beneficiary that owns the destination wallet address. Possible values: INDIVIDUAL, BUSINESS enum: - INDIVIDUAL - BUSINESS example: INDIVIDUAL address: description: >- The physical address of the beneficiary that owns the destination wallet address allOf: - $ref: '#/components/schemas/BeneficiaryAddressDto' first_name: type: string description: >- The first name of the individual beneficiary. Required if type is INDIVIDUAL example: John last_name: type: string description: >- The last name of the individual beneficiary. Required if type is INDIVIDUAL example: Doe business_name: type: string description: >- The legal business name of the beneficiary. Required if type is BUSINESS example: Acme Corp email: type: string description: >- Email address of the beneficiary. Required for off-ramp bank account destinations example: john.doe@example.com tax_identification_number: type: string description: >- The beneficiary's tax identification number. Required for some local corridors (e.g. PEN, BOB, CLP, COP, CRC, USD in Ecuador). example: '20123456789' phone: type: string description: >- The beneficiary's phone number. Required for some local corridors (e.g. CRC, COP, USD in Ecuador). example: '+50688881234' required: - type - address BeneficiaryAddressDto: type: object properties: country_code: type: string description: >- The country code of the beneficiary's address, in ISO 3166-1 alpha-2 format example: US street_line1: type: string description: >- Street address line 1. Required for off-ramp bank account destinations example: 123 Main St street_line2: type: string description: Street address line 2 example: Suite 100 city: type: string description: City. Required for off-ramp bank account destinations example: New York state_region_or_province: type: string description: >- State, region, or province. Required for off-ramp bank account destinations example: NY postal_code: type: string description: Postal code. Required for off-ramp bank account destinations example: '10001' required: - country_code securitySchemes: api-key: type: apiKey in: header name: X-Api-Key ````