Overview
Settlement request object is created when you want to request real-time settlement from Superbank. You can create settlement requests, retrieve individual settlement requests, list all settlement requests and update individual settlement requests.
Endpoints
POST/v0/settlement-requestsGET/v0/settlement-requestsGET/v0/settlement-requests/:idPUT/v0/settlement-requests/:id
Object
Attributes
| Attribute | Description |
|---|---|
id | The unique identifier of the settlement request. |
status | The current lifecycle status of the settlement request. |
amount | The amount of the settlement request. |
destination | The destination details for the settlement. |
destination.currency | The currency in which the settlement is paid. |
destination.rail | The payment rail used for the settlement. |
destination.wallet_address | The wallet address receiving the settlement funds. |
destination.beneficiary | The beneficiary that owns the destination wallet address. |
destination.beneficiary.type | The beneficiary type. |
destination.beneficiary.address | The physical address of the beneficiary. |
destination.beneficiary.address.country_code | The beneficiary’s country code in ISO 3166-1 alpha-2 format. |
destination.beneficiary.first_name | The first name of the individual beneficiary. |
destination.beneficiary.last_name | The last name of the individual beneficiary. |
destination.beneficiary.business_name | The legal business name of the beneficiary. |
payment_instructions | Instructions describing the inbound payment from the user to pre-funded wallet. |
payment_instructions.currency | The currency of the inbound payment. |
payment_instructions.rail | The rail of the inbound payment |
payment_instructions.prefunded_wallet_address | The pre-funded wallet address to be used as a destination for the inbound payment. |
payment_instructions.valid_until | The timestamp until which the inbound payment instructions remain valid. |
transaction_id | The external transaction identifier associated with the settlement request. |
outbound_payment | The outbound (instant) payment sent from the pre-funded wallet to the destination. |
outbound_payment.id | The unique identifier of the outbound payment. |
outbound_payment.type | The type of outbound payment. |
outbound_payment.status | The status of the outbound payment. |
outbound_payment.amount | The amount of the outbound payment. |
outbound_payment.currency | The currency of the outbound payment. |
outbound_payment.created_at | The timestamp when the outbound payment was created. |
inbound_payment | The inbound payment received from an external source into the pre-funded wallet. |
inbound_payment.id | The unique identifier of the inbound payment. |
inbound_payment.type | The type of inbound payment. |
inbound_payment.status | The current status of the inbound payment. |
inbound_payment.amount | The amount of the inbound payment. |
inbound_payment.currency | The currency of the inbound payment. |
inbound_payment.created_at | The timestamp when the inbound payment was created. |
created_at | The timestamp when the settlement request was created. |
updated_at | The timestamp of the most recent update to the settlement request. |
processing_at | The timestamp when settlement processing began. |
completed_at | The timestamp when the settlement request was completed. |
Statuses
| Status | Description |
|---|---|
REQUEST_STARTED | The settlement request is created, the end user did not send funds to the pre-funded wallet. The payment instructions are returned to the developer. |
REQUEST_EXPIRED | The end user did not send payment from their account, to developer’s pre-funded wallet on Superbank, within 15 minutes after the settlement request was created. The Developer needs to create a new request to initiate a new settlement request. |
REQUEST_CANCELED | Settlement request was canceled by the developer. |
REQUEST_COMPLETED | The funds sent from the end user, have arrived on the pre-funded wallet and the transaction hash was matched with the transaction hash of the payment that arrived to the pre-funded wallet. This status change completes the individual settlement request. |
AWAITING_PAYIN_RECONCILIATION | The developer called REQUEST_COMPLETED with a transaction_hash, but Superbank has not yet observed the matching inbound payment on the pre-funded wallet. Superbank defers the amount check until the inbound payment lands; the request then resolves automatically to REQUEST_COMPLETED (or PAYIN_AMOUNT_MISMATCH if the received amount differs from the settlement amount). No action required from the developer. |
PAYIN_AMOUNT_MISMATCH | The inbound payment was received on the pre-funded wallet, but its amount does not match the settlement amount. Terminal — resolve manually. |
REQUEST_REFUNDED | The end-user refunded payment from pre-funded wallet to their wallet, Superbank refunded payment from the end-user bank account to pre-funded wallet. |
FUNDS_SENT | The end user sent the funds to the pre-funded wallet, but the transaction hash was not matched to the settlement request. This status change initiates instant settlement from the Developer’s pre-funded account to the End-User’s wallet. |
SETTLEMENT_SENT | Superbank sent funds from pre-funded wallet to end-user’s account. |
SETTLEMENT_COMPLETED | The funds sent by Superbank from pre-funded wallet have arrived to the end-user’s account. |
PAYIN_CANCELED | Payment from the end-user’s account, to pre-funded wallet was canceled. |
PAYIN_UNDER_REVIEW | Payment from the end-user’s account to the developer’s pre-funded wallet on Superbank is under compliance review. |
PAYIN_FAILED | Payment from the end-user’s account, to developer’s Superbank pre-funded wallet failed. |
PAYOUT_CANCELED | Payment to the developer’s pre-funded wallet on Superbank, to the end-user’s account was canceled. |
PAYOUT_UNDER_REVIEW | Payment to the developer’s pre-funded wallet on Superbank to the end-user’s account is under compliance review. |
PAYOUT_FAILED | Payment to developer’s pre-funded Superbank wallet, to the end-user’s account failed. |
Endpoints
POST /v0/settlement-requests
Parameters
| Path parameter | Description |
|---|---|
| None | This endpoint does not require path parameters. |
| Body parameter | Description |
amount | The amount to be settled. |
destination | The destination where the settlement funds will be sent. |
destination.currency | The currency in which the settlement will be paid. |
destination.rail | The payment rail used to deliver the settlement (for example, blockchain or bank transfer). |
destination.wallet_address | The wallet address that will receive the settlement funds. |
destination.beneficiary | The beneficiary that owns the destination wallet address. |
destination.beneficiary.type | The type of beneficiary that owns the destination wallet address. |
destination.beneficiary.address | The physical address of the beneficiary that owns the destination wallet address. |
destination.beneficiary.address.country_code | The country code of the beneficiary’s address, in ISO 3166-1 alpha-2 format. |
destination.beneficiary.first_name | The first name of the individual beneficiary. |
destination.beneficiary.last_name | The last name of the individual beneficiary. |
destination.beneficiary.business_name | The legal business name of the beneficiary. |
Request
curl --request POST \
--url https://api-sandbox.superbank.co/v0/settlement-requests \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: YOUR_API_KEY' \
--data '{
"amount": 20,
"destination": {
"currency": "USDC",
"rail": "SOLANA",
"wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
"beneficiary": {
"type": "BUSINESS",
"address": {
"country_code": "US"
},
"business_name": "Acme Corp"
}
}
}'
Response
{
"id": "39760060-846e-4d5a-8583-7ee62553f79b",
"status": "REQUEST_STARTED",
"amount": "20",
"transaction_id": null,
"destination": {
"currency": "USDC",
"rail": "SOLANA",
"wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
"beneficiary": {
"type": "BUSINESS",
"business_name": "Acme Corp",
"address": {
"country_code": "US"
}
}
},
"payment_instructions": {
"currency": "USDC",
"rail": "SOLANA",
"prefunded_wallet_address": "AWE1XaAdRuxzjqy8Q7q75MFbPTs1W6Zbp3zvYWcDGjTj",
"valid_until": "2026-01-26T15:50:10.074Z"
},
"outbound_payment": null,
"inbound_payment": null,
"created_at": "2026-01-26T15:45:10.047Z",
"updated_at": "2026-01-26T15:45:10.047Z",
"processing_at": null,
"completed_at": null
}
GET /v0/settlement-requests
Parameters
| Path parameter | Description |
|---|---|
| None | This endpoint does not require path parameters. |
| Body parameter | Description |
page | The page number to retrieve. Pages are 1-indexed. If omitted, defaults to the first page. |
limit | The maximum number of settlement requests to return per page. If omitted, defaults to 20. Maximum is 100. |
status | Filters settlement requests by status. If omitted, settlement requests of all statuses are returned. |
Request
curl --request GET \
--url https://api-sandbox.superbank.co/v0/settlement-requests \
--header 'X-Api-Key: YOUR_API_KEY'
Response
{
"data": [
{
"id": "514a178d-f3e1-4751-8d12-5005cc636507",
"status": "REQUEST_COMPLETED",
"amount": "20.00000000",
"transaction_id": null,
"destination": {
"currency": "USDC",
"rail": "SOLANA",
"wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
"beneficiary": {
"type": "BUSINESS",
"business_name": "Fake Corp",
"address": {
"country_code": "US"
}
}
},
"payment_instructions": {
"currency": "USDC",
"rail": "SOLANA",
"prefunded_wallet_address": "CfYk4qqeqqHRNzpzrYnXz2A9kmqZXCuiA8UkxNe7wvPs",
"valid_until": "2026-01-29T11:52:25.445Z"
},
"outbound_payment": {
"id": "b3d44d69-c0d4-4aec-85b0-f024e665ad13",
"type": "PAYOUT",
"status": "COMPLETED",
"amount": "20.00000000",
"currency": "USDC",
"created_at": "2026-01-29T11:38:18.948Z"
},
"inbound_payment": {
"id": "6c7484fd-405d-4681-ba36-773b2ade1aae",
"type": "PAYIN",
"status": "COMPLETED",
"amount": "20.00000000",
"currency": "USDC",
"created_at": "2026-01-29T11:23:08.433Z"
},
"created_at": "2026-01-29T11:37:25.112Z",
"updated_at": "2026-01-29T11:44:08.318Z",
"processing_at": "2026-01-29T11:38:18.965Z",
"completed_at": "2026-01-29T11:44:08.305Z"
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 1,
"total_pages": 1
}
}
GET /v0/settlement-requests/:id
Parameters
| Path parameter | Description |
|---|---|
id | The unique identifier of the settlement request. |
| Body parameter | Description |
| None | This endpoint does not require body parameters. |
Request
curl --request GET \
--url https://api-sandbox.superbank.co/v0/settlement-requests/514a178d-f3e1-4751-8d12-5005cc636507 \
--header 'X-Api-Key: YOUR_API_KEY'
Response
{
"id": "514a178d-f3e1-4751-8d12-5005cc636507",
"status": "REQUEST_COMPLETED",
"amount": "20.00000000",
"transaction_id": null,
"destination": {
"currency": "USDC",
"rail": "SOLANA",
"wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
"beneficiary": {
"type": "BUSINESS",
"business_name": "Fake Corp",
"address": {
"country_code": "US"
}
}
},
"payment_instructions": {
"currency": "USDC",
"rail": "SOLANA",
"prefunded_wallet_address": "CfYk4qqeqqHRNzpzrYnXz2A9kmqZXCuiA8UkxNe7wvPs",
"valid_until": "2026-01-29T11:52:25.445Z"
},
"outbound_payment": {
"id": "b3d44d69-c0d4-4aec-85b0-f024e665ad13",
"type": "PAYOUT",
"status": "COMPLETED",
"amount": "20.00000000",
"currency": "USDC",
"created_at": "2026-01-29T11:38:18.948Z"
},
"inbound_payment": {
"id": "6c7484fd-405d-4681-ba36-773b2ade1aae",
"type": "PAYIN",
"status": "COMPLETED",
"amount": "20.00000000",
"currency": "USDC",
"created_at": "2026-01-29T11:23:08.433Z"
},
"created_at": "2026-01-29T11:37:25.112Z",
"updated_at": "2026-01-29T11:44:08.318Z",
"processing_at": "2026-01-29T11:38:18.965Z",
"completed_at": "2026-01-29T11:44:08.305Z"
}
PUT /v0/settlement-requests/:id
Parameters
| Path parameter | Description |
|---|---|
id | The unique identifier of the settlement request. |
| Body parameter | Description |
status | The status to update the settlement request to. |
transaction_id | The external transaction identifier that will be associated with the settlement request. |
transaction_hash | The transaction hash that will be associated with the settlement request. |
Request
curl --request PUT \
--url https://api-sandbox.superbank.co/v0/settlement-requests/514a178d-f3e1-4751-8d12-5005cc636507 \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: YOUR_API_KEY' \
--data '{
"status": "FUNDS_SENT"
}'
Response
{
"id": "514a178d-f3e1-4751-8d12-5005cc636507",
"status": "FUNDS_SENT",
"amount": "20.00000000",
"transaction_id": null,
"destination": {
"currency": "USDC",
"rail": "SOLANA",
"wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
"beneficiary": {
"type": "BUSINESS",
"business_name": "Fake Corp",
"address": {
"country_code": "US"
}
}
},
"payment_instructions": {
"currency": "USDC",
"rail": "SOLANA",
"prefunded_wallet_address": "CfYk4qqeqqHRNzpzrYnXz2A9kmqZXCuiA8UkxNe7wvPs",
"valid_until": "2026-01-29T11:52:25.445Z"
},
"outbound_payment": {
"id": "b3d44d69-c0d4-4aec-85b0-f024e665ad13",
"type": "PAYOUT",
"status": "COMPLETED",
"amount": "20.00000000",
"currency": "USDC",
"created_at": "2026-01-29T11:38:18.948Z"
},
"inbound_payment": null,
"created_at": "2026-01-29T11:37:25.112Z",
"updated_at": "2026-01-29T11:44:08.318Z",
"processing_at": "2026-01-29T11:38:18.965Z",
"completed_at": null
}