Skip to main content
POST
/
v0
/
settlement-requests
Create a settlement request
curl --request POST \
  --url https://api-sandbox.superbank.co/v0/settlement-requests \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "type": "FIAT_TO_STABLECOIN",
  "payment_reason": "REMITTANCES",
  "destination": {
    "is_third_party": true,
    "rail": "SOLANA",
    "currency": "USDC",
    "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "beneficiary": {
      "type": "INDIVIDUAL",
      "address": {
        "country_code": "US",
        "street_line1": "123 Main St",
        "street_line2": "Suite 100",
        "city": "New York",
        "state_region_or_province": "NY",
        "postal_code": "10001"
      },
      "first_name": "John",
      "last_name": "Doe",
      "business_name": "Acme Corp",
      "email": "john.doe@example.com",
      "tax_identification_number": "20123456789",
      "phone": "+50688881234"
    }
  },
  "amount": 99
}
'
{
  "id": "d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f8a",
  "type": "FIAT_TO_STABLECOIN",
  "payment_reason": "REMITTANCES",
  "status": "REQUEST_STARTED",
  "amount": "99.00",
  "destination": {},
  "payment_instructions": {
    "currency": "USDC",
    "rail": "SOLANA",
    "valid_until": "2026-01-20T15:22:12.805Z",
    "amount": "729.16",
    "wallet_address": "FRNthe6oqA8fhVMfXMM12rGmFYvejtkmH3bRfYBxWnLB",
    "chain": "SOLANA",
    "bank_name": "JPMorgan Chase",
    "account_number": "123456789",
    "routing_number": "021000021",
    "deposit_message": "SB-39760060",
    "destination_amount": "1000.00",
    "destination_currency": "CAD",
    "exchange_rate": "1.3788512205",
    "fee": {
      "fixed": 1,
      "variable": 0.005,
      "total": 6
    }
  },
  "created_at": "2026-01-20T15:17:12.805Z",
  "updated_at": "2026-01-20T15:20:00.000Z",
  "external_id": "order_abc123",
  "metadata": {
    "restaurant_id": "rest_42",
    "source": "web"
  },
  "transaction_id": "your_trx_123",
  "source": {
    "currency": "USDC",
    "rail": "SOLANA",
    "wallet_address": "0x388C818CA8B9251b393131C08a736A67ccB19297"
  },
  "outbound_payment": {
    "id": "d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f8a",
    "type": "PAYOUT",
    "status": "PROCESSING",
    "amount": "99.00",
    "currency": "USDC",
    "created_at": "2026-01-20T15:20:00.000Z"
  },
  "inbound_payment": {
    "id": "d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f8a",
    "type": "PAYOUT",
    "status": "PROCESSING",
    "amount": "99.00",
    "currency": "USDC",
    "created_at": "2026-01-20T15:20:00.000Z"
  },
  "processing_at": "2026-01-20T15:20:00.000Z",
  "completed_at": "2026-01-20T15:25:00.000Z",
  "reconciliation_expected_at": "2026-01-23T15:20:00.000Z",
  "failure_code": "AMOUNT_MISMATCH_UNDERPAYMENT",
  "failure_reason": "Amount mismatch: expected 100.00, received 90.00"
}

Authorizations

​
X-Api-Key
string
header
required

Headers

​
Idempotency-Key
string

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.

Body

application/json
​
type
enum<string>
required

The type of settlement request

Available options:
STABLECOIN_TO_STABLECOIN,
FIAT_TO_STABLECOIN,
STABLECOIN_TO_FIAT,
FIAT_TO_FIAT
Example:

"FIAT_TO_STABLECOIN"

​
payment_reason
enum<string>
required

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.

Available options:
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"

​
destination
Crypto · object
required

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.
​
amount
number

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.

Required range: x >= 0.01
Example:

99

​
source
Crypto · object

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

​
external_id
string

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

Maximum string length: 255
Example:

"order_abc123"

​
metadata
object

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"
}
​
reconciliation_expected_at
string

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"

Response

Settlement request created with status OPEN

​
id
string
required

The unique identifier of the settlement request

Example:

"d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f8a"

​
type
enum<string>
required

The type of settlement request

Available options:
STABLECOIN_TO_STABLECOIN,
FIAT_TO_STABLECOIN,
STABLECOIN_TO_FIAT,
FIAT_TO_FIAT
Example:

"FIAT_TO_STABLECOIN"

​
payment_reason
enum<string>
required

Reason for the payment; internal for the sender

Available options:
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
enum<string>
required

The current lifecycle status of the settlement request

Available options:
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
string
required

The amount of the settlement request

Example:

"99.00"

​
destination
object
required

The destination details for the settlement

​
payment_instructions
object
required

Instructions describing the inbound payment

​
created_at
string
required

The timestamp when the settlement request was created

Example:

"2026-01-20T15:17:12.805Z"

​
updated_at
string
required

The timestamp of the most recent update

Example:

"2026-01-20T15:20:00.000Z"

​
external_id
object

An identifier you supplied for this settlement (e.g. your internal order id). Filterable via GET /v0/settlement-requests?external_id=....

Example:

"order_abc123"

​
metadata
object

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"
}
​
transaction_id
object
deprecated

Deprecated — removal: 2026-05-25. Use external_id. Same value, kept for compatibility until the removal date.

Example:

"your_trx_123"

​
source
object

The source details (for off-ramp)

​
outbound_payment
object

The outbound payment from the pre-funded wallet to the destination

​
inbound_payment
object

The inbound payment received from an external source

​
processing_at
object

The timestamp when processing began

Example:

"2026-01-20T15:20:00.000Z"

​
completed_at
object

The timestamp when completed

Example:

"2026-01-20T15:25:00.000Z"

​
reconciliation_expected_at
object

The timestamp when funds are expected to reconcile

Example:

"2026-01-23T15:20:00.000Z"

​
failure_code
enum<string> | null

Structured failure code for programmatic handling

Available options:
AMOUNT_MISMATCH_UNDERPAYMENT,
AMOUNT_MISMATCH_OVERPAYMENT
Example:

"AMOUNT_MISMATCH_UNDERPAYMENT"

​
failure_reason
object

Human-readable failure reason

Example:

"Amount mismatch: expected 100.00, received 90.00"