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",
  "amount": 99,
  "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"
    }
  }
}
'
{
  "id": "d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f8a",
  "type": "FIAT_TO_STABLECOIN",
  "payment_reason": "REMITTANCES",
  "status": "REQUEST_STARTED",
  "amount": "99.00",
  "destination": {},
  "payment_instructions": {
    "amount": "99.00",
    "currency": "USDC",
    "rail": "SOLANA",
    "valid_until": "2026-01-20T15:22:12.805Z",
    "wallet_address": "0x12345678900987654321234567890",
    "chain": "SOLANA",
    "bank_name": "JPMorgan Chase",
    "account_number": "123456789",
    "routing_number": "021000021",
    "deposit_message": "SB-39760060"
  },
  "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"
}

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.

Authorizations

​
X-Api-Key
string
header
required

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"

​
amount
number
required

The amount to be settled

Required range: x >= 0.01
Example:

99

​
destination
Crypto · object
required

The destination where the settlement funds will be sent. Discriminated by rail: crypto rails use wallet_address, ACH/RTP/WIRE use bank fields, SEPA uses iban/bic, SPEI uses clabe, NIBSS uses account_number/bank_code

​
source
object

The source of funds. Required for STABLECOIN_TO_FIAT and FIAT_TO_STABLECOIN

​
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"