> ## 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. # 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 * [`POST` /v0/settlement-requests](/platform/core-resources/settlement-request#post-/v0/settlement-requests) * [`GET` /v0/settlement-requests](/platform/core-resources/settlement-request#get-/v0/settlement-requests) * [`GET` /v0/settlement-requests/:id](/platform/core-resources/settlement-request#get-/v0/settlement-requests/:id) * [`PUT` /v0/settlement-requests/:id](/platform/core-resources/settlement-request#put-/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 ```bash theme={null} 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 ```json theme={null} { "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 ```bash theme={null} curl --request GET \ --url https://api-sandbox.superbank.co/v0/settlement-requests \ --header 'X-Api-Key: YOUR_API_KEY' ``` #### Response ```json theme={null} { "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 ```bash theme={null} 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 ```json theme={null} { "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 ```bash theme={null} 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 ```json theme={null} { "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 } ```