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": "PERSONAL_TRANSFERS",
  "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
}
'

import requests

url = "https://api-sandbox.superbank.co/v0/settlement-requests"

payload = {
    "type": "FIAT_TO_STABLECOIN",
    "payment_reason": "PERSONAL_TRANSFERS",
    "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
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: 'FIAT_TO_STABLECOIN',
    payment_reason: 'PERSONAL_TRANSFERS',
    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
  })
};

fetch('https://api-sandbox.superbank.co/v0/settlement-requests', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f8a",
  "type": "FIAT_TO_STABLECOIN",
  "payment_reason": "PERSONAL_TRANSFERS",
  "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"
}

POST

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": "PERSONAL_TRANSFERS",
  "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
}
'

import requests

url = "https://api-sandbox.superbank.co/v0/settlement-requests"

payload = {
    "type": "FIAT_TO_STABLECOIN",
    "payment_reason": "PERSONAL_TRANSFERS",
    "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
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: 'FIAT_TO_STABLECOIN',
    payment_reason: 'PERSONAL_TRANSFERS',
    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
  })
};

fetch('https://api-sandbox.superbank.co/v0/settlement-requests', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f8a",
  "type": "FIAT_TO_STABLECOIN",
  "payment_reason": "PERSONAL_TRANSFERS",
  "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 enum mirrors the upstream regulatory taxonomy - most fintech integrations only need a small subset. Common values for fintech use cases: PERSONAL_TRANSFERS (cross-border consumer transfers), FAMILY_SUPPORT (remittances to family), PURCHASE_OF_GOODS / PURCHASE_OF_SERVICES (merchant payments), EMPLOYEE_SALARIES_OR_WAGES (payroll). Pick the closest specific value. Deprecated values from the previous taxonomy (e.g. REMITTANCES, PAYMENT_FOR_GOODS_AND_SERVICES) are still accepted and translated automatically.

Available options:

CHARITABLE_CONTRIBUTIONS,

CONSULTING_FEES,

EDUCATION_FEES,

EMPLOYEE_SALARIES_OR_WAGES,

FAMILY_SUPPORT,

GIFTS,

INSURANCE,

INTERCOMPANY_TRANSFER,

INVESTMENTS,

LOANS,

PERSONAL_TRANSFERS,

PURCHASE_OF_GOODS,

PURCHASE_OF_SERVICES,

REAL_ESTATE,

RENT,

TAXES,

TRAVEL,

UTILITY_BILLS

Example:

"PERSONAL_TRANSFERS"

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.

Crypto
US bank (ABA)
IBAN (EUR/GBP + EU/ME locals)
CLABE (Mexico)
Account + bank code (Nigeria)
Local account (LATAM)
Specialized (IFSC / BSB / CNAPS / branch)

Show child attributes

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

Crypto
Fiat

Show child attributes

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.

Show child attributes

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

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:

CHARITABLE_CONTRIBUTIONS,

CONSULTING_FEES,

EDUCATION_FEES,

EMPLOYEE_SALARIES_OR_WAGES,

FAMILY_SUPPORT,

GIFTS,

INSURANCE,

INTERCOMPANY_TRANSFER,

INVESTMENTS,

LOANS,

PERSONAL_TRANSFERS,

PURCHASE_OF_GOODS,

PURCHASE_OF_SERVICES,

REAL_ESTATE,

RENT,

TAXES,

TRAVEL,

UTILITY_BILLS

Example:

"PERSONAL_TRANSFERS"

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

Show child attributes

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 | null

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 | null

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.

Show child attributes

Example:

{
  "restaurant_id": "rest_42",
  "source": "web"
}

transaction_id

object | null

deprecated

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

Example:

"your_trx_123"

source

object | null

The source details (for off-ramp)

Show child attributes

outbound_payment

object | null

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

Show child attributes

inbound_payment

object | null

The inbound payment received from an external source

Show child attributes

processing_at

object | null

The timestamp when processing began

Example:

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

completed_at

object | null

The timestamp when completed

Example:

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

reconciliation_expected_at

object | null

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 | null

Human-readable failure reason

Example:

"Amount mismatch: expected 100.00, received 90.00"

Introduction

Settlement Requests

Payments

Rates

Disbursements

Webhooks

Sandbox

Create a settlement request

Authorizations

Headers

Body

Response