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

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

Reason for the payment; this is internal for the sender and not visible to the recipient.

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

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"

​
transaction_id
object

The external transaction identifier

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 arrive (72h on-ramp, 10min off-ramp)

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"