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"
}
'

import requests

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

payload = { "status": "FUNDS_SENT" }
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({status: 'FUNDS_SENT'})
};

fetch('https://api-sandbox.superbank.co/v0/settlement-requests/{id}', 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"
}

PUT

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"
}
'

import requests

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

payload = { "status": "FUNDS_SENT" }
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({status: 'FUNDS_SENT'})
};

fetch('https://api-sandbox.superbank.co/v0/settlement-requests/{id}', 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

Path Parameters

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

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"

⌘I

Introduction

Settlement Requests

Payments

Rates

Disbursements

Webhooks

Sandbox

Update settlement request status

Authorizations

Path Parameters

Body

Response