Settlement Request

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

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.
`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 /v1/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/v1/settlement-requests \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: sb_test_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 /v1/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/v1/settlement-requests \
--header 'X-Api-Key: sb_test_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 /v1/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/v1/settlement-requests/514a178d-f3e1-4751-8d12-5005cc636507 \
--header 'X-Api-Key: sb_test_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 /v1/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/v1/settlement-requests/514a178d-f3e1-4751-8d12-5005cc636507 \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: sb_test_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
}

Guides

API Instructions

Core Resources

Changelog

Overview

Object

Attributes

Statuses

Endpoints

`POST /v1/settlement-requests`

Parameters

Request

Response

`GET /v1/settlement-requests`

Parameters

Request

Response

`GET /v1/settlement-requests/:id`

Parameters

Request

Response

`PUT /v1/settlement-requests/:id`

Parameters

Request

Response

Guides

API Instructions

Core Resources

Changelog

​Overview

​Object

​Attributes

​Statuses

​Endpoints

​POST /v1/settlement-requests

​Parameters

​Request

​Response

​GET /v1/settlement-requests

​Parameters

​Request

​Response

​GET /v1/settlement-requests/:id

​Parameters

​Request

​Response

​PUT /v1/settlement-requests/:id

​Parameters

​Request

​Response

Overview

Object

Attributes

Statuses

Endpoints

`POST /v1/settlement-requests`

Parameters

Request

Response

`GET /v1/settlement-requests`

Parameters

Request

Response

`GET /v1/settlement-requests/:id`

Parameters

Request

Response

`PUT /v1/settlement-requests/:id`

Parameters

Request

Response