Skip to main content
PUT
/
v0
/
settlement-requests
/
{id}
Update settlement request status
curl --request PUT \
  --url https://api-sandbox.superbank.co/v0/settlement-requests/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "status": "FUNDS_SENT"
}
'
{
  "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

Path Parameters

​
id
string
required

The unique identifier of the settlement request

Body

application/json
​
status
enum<string>
required

The status to update the settlement request to

Available options:
FUNDS_SENT,
REQUEST_COMPLETED,
REQUEST_CANCELED,
PAYIN_CANCELED,
PAYIN_UNDER_REVIEW,
PAYIN_FAILED,
PAYIN_AMOUNT_MISMATCH
Example:

"FUNDS_SENT"

​
external_id
string

An identifier of your choice for this settlement. Same field as external_id on create — provided here for clients that set the identifier at FUNDS_SENT time rather than on create.

Maximum string length: 255
Example:

"order_abc123"

​
transaction_id
string
deprecated

Deprecated — removal: 2026-05-25. Use external_id instead. Both fields map to the same underlying value; if both are sent, external_id wins.

Example:

"your_trx_123"

​
transaction_hash
string

The transaction hash that will be associated with the settlement request

Example:

"5K8z2tF3mN9pQrS4uV6wX7yZ1aB2cD3eF4gH5iJ6kL7m8N9oP0qR1sT2uV3wX4yZ5a"

Response

Settlement request updated

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