Overview
Payment object is created when funds leave or land to/from your Superbank accounts and wallets. You can list all and retrieve individual payments.
Endpoints
Object
Attributes
| Attribute | Description |
|---|---|
id | The unique identifier of the payment |
type | The type of the payment. |
status | The current lifecycle status of the payment. |
source | The source of the payment funds. |
source.amount | The amount sent from the payment source. |
source.currency | The currency code of the source amount. |
source.rail | The payment rail used by the source. |
source.wallet_address | The wallet address of the source. |
source.transaction_hash | The transaction hash of the payment. |
destination | The destination of the payment funds. |
destination.amount | The amount received by the destination. |
destination.currency | The currency code of the destinaton amount. |
destination.rail | The payment rail used by the destination. |
destination.wallet_address | The wallet address of the destination. |
destination.transaction_hash | The transaction hash of the payment. |
settlement_request_id | The unique identifier of the settlement request associated with the payment. |
fee | The developer fee charged for processing the payment. |
metadata | The medatada associated with the payment. |
metadata.order_id | Order identifier associated with the payment. |
failure_reason | The reason why the payment failed, if applicable. |
created_at | The timestamp when the payment was created. |
updated_at | The timestamp of the most recent update to the payment. |
completed_at | The timestamp when the payment was completed. |
Types
| Type | Description |
|---|---|
PAYIN | Funds are transferred from an external account into a virtual account. Commonly used to represent deposits or inbound funding (e.g., external bank account → virtual bank account). |
PAYOUT | Funds are transferred from a virtual account to an external account. Commonly used to represent withdrawals or outbound payments (e.g., virtual bank account → external digital asset wallet). |
INTERNAL | Funds are transferred between two virtual accounts within Superbank (e.g., virtual bank account → virtual digital asset wallet). |
EXTERNAL | Funds are transferred between two external accounts without involving a virtual account as the source or destination (e.g., external bank account → external digital asset wallet). |
Statuses
| Status | Description |
|---|---|
AWAITING_FUNDS | The payment has been created but does not yet have a funded source. The end user is expected to send funds to proceed. Payments in this state expire after a predefined time window. |
EXPIRED | The payment remained in AWAITING_FUNDS beyond the allowed funding period and is no longer eligible to receive funds. Any incoming funds should not be sent to this payment. |
PENDING | The payment has been funded and has passed initial validation checks. It is ready to be initiated for processing. |
PROCESSING | The payment is actively being processed. Payment instructions have been submitted to the relevant rail or financial institution. If foreign exchange is required, the conversion is executed during this stage. |
SENT | The funds have been released from the source and are in transit to the destination. Final settlement has not yet been confirmed. |
COMPLETED | The destination has successfully received the funds, and the payment lifecycle is complete. |
CANCELLED | The payment was intentionally cancelled before funds were released. No transfer was executed. |
FAILED | The payment could not be initiated or completed due to an error or rejection. No further processing will occur unless retried or recreated. |
REFUNDED | Funds associated with the payment have been returned to the original funding source. |
UNDER_REVIEW | The payment is temporarily paused pending compliance, risk, or regulatory review. Processing will resume or terminate once the review is complete. |
Endpoints
GET /v0/payments
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 payments to return per page. If omitted, defaults to 20. Maximum is 100. |
status | Filters payments by status. If omitted, payments of all statuses are returned. |
Request
curl --request GET \
--url 'https://api-sandbox.superbank.co/v0/payments?page=1&limit=20' \
--header 'X-Api-Key: YOUR_API_KEY'
Response
{
"data": [
{
"id": "6c7484fd-405d-4681-ba36-773b2ade1aae",
"settlement_request_id": null,
"type": "PAYIN",
"status": "COMPLETED",
"fee": null,
"source": {
"amount": "20.00000000",
"currency": "USDC",
"rail": "SOLANA",
"wallet_address": "H3sjyipQtXAJkvWNkXhDgped7k323kAba8QMwCLcV79w",
"transaction_hash": "2hKzwU3RvVdHPA5enywioqM46sqNfPLrmu9kZY1VoiBbHanoWEHvvEtRshSJUfyF7LuMxbwSoEX3C5gVV6DLrrC7"
},
"destination": {
"amount": "20.00000000",
"currency": "USDC",
"rail": "SOLANA",
"wallet_address": "CfYk4qqeqqHRNzpzrYnXz2A9kmqZXCuiA8UkxNe7wvPs",
"transaction_hash": null
},
"metadata": null,
"failure_reason": null,
"created_at": "2026-01-29T11:23:08.433Z",
"updated_at": "2026-01-29T11:23:08.433Z",
"completed_at": "2026-01-29T11:23:08.431Z"
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 1,
"total_pages": 1
}
}
GET /v0/payments/:id
Parameters
| Path parameter | Description |
|---|---|
id | The unique identifier of the payment. |
| Body parameter | Description |
| None | This endpoint does not require path parameters. |
Request
curl --request GET \
--url https://api-sandbox.superbank.co/v0/payments/6c7484fd-405d-4681-ba36-773b2ade1aae \
--header 'X-Api-Key: YOUR_API_KEY'
Response
{
"id": "6c7484fd-405d-4681-ba36-773b2ade1aae",
"settlement_request_id": null,
"type": "PAYIN",
"status": "COMPLETED",
"fee": null,
"source": {
"amount": "20.00000000",
"currency": "USDC",
"rail": "SOLANA",
"wallet_address": "H3sjyipQtXAJkvWNkXhDgped7k323kAba8QMwCLcV79w",
"transaction_hash": "2hKzwU3RvVdHPA5enywioqM46sqNfPLrmu9kZY1VoiBbHanoWEHvvEtRshSJUfyF7LuMxbwSoEX3C5gVV6DLrrC7"
},
"destination": {
"amount": "20.00000000",
"currency": "USDC",
"rail": "SOLANA",
"wallet_address": "CfYk4qqeqqHRNzpzrYnXz2A9kmqZXCuiA8UkxNe7wvPs",
"transaction_hash": null
},
"metadata": null,
"failure_reason": null,
"created_at": "2026-01-29T11:23:08.433Z",
"updated_at": "2026-01-29T11:23:08.433Z",
"completed_at": "2026-01-29T11:23:08.431Z"
}