Skip to main content

​
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

AttributeDescription
idThe unique identifier of the payment
typeThe type of the payment.
statusThe current lifecycle status of the payment.
sourceThe source of the payment funds.
source.amountThe amount sent from the payment source.
source.currencyThe currency code of the source amount.
source.railThe payment rail used by the source.
source.wallet_addressThe wallet address of the source.
source.transaction_hashThe transaction hash of the payment.
destinationThe destination of the payment funds.
destination.amountThe amount received by the destination.
destination.currencyThe currency code of the destinaton amount.
destination.railThe payment rail used by the destination.
destination.wallet_addressThe wallet address of the destination.
destination.transaction_hashThe transaction hash of the payment.
settlement_request_idThe unique identifier of the settlement request associated with the payment.
feeThe developer fee charged for processing the payment.
metadataThe medatada associated with the payment.
metadata.order_idOrder identifier associated with the payment.
failure_reasonThe reason why the payment failed, if applicable.
created_atThe timestamp when the payment was created.
updated_atThe timestamp of the most recent update to the payment.
completed_atThe timestamp when the payment was completed.

​
Types

TypeDescription
PAYINFunds 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).
PAYOUTFunds 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).
INTERNALFunds are transferred between two virtual accounts within Superbank (e.g., virtual bank account → virtual digital asset wallet).
EXTERNALFunds 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

StatusDescription
AWAITING_FUNDSThe 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.
EXPIREDThe 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.
PENDINGThe payment has been funded and has passed initial validation checks. It is ready to be initiated for processing.
PROCESSINGThe 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.
SENTThe funds have been released from the source and are in transit to the destination. Final settlement has not yet been confirmed.
COMPLETEDThe destination has successfully received the funds, and the payment lifecycle is complete.
CANCELLEDThe payment was intentionally cancelled before funds were released. No transfer was executed.
FAILEDThe payment could not be initiated or completed due to an error or rejection. No further processing will occur unless retried or recreated.
REFUNDEDFunds associated with the payment have been returned to the original funding source.
UNDER_REVIEWThe payment is temporarily paused pending compliance, risk, or regulatory review. Processing will resume or terminate once the review is complete.

​
Endpoints

​
GET /v1/payments

​
Parameters

Path parameterDescription
NoneThis endpoint does not require path parameters.
Body parameterDescription
pageThe page number to retrieve. Pages are 1-indexed. If omitted, defaults to the first page.
limitThe maximum number of payments to return per page. If omitted, defaults to 20. Maximum is 100.
statusFilters payments by status. If omitted, payments of all statuses are returned.

​
Request

curl --request GET \
  --url 'https://api-sandbox.superbank.co/v1/payments?page=1&limit=20' \
  --header 'X-Api-Key: sb_test_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 /v1/payments/:id

​
Parameters

Path parameterDescription
idThe unique identifier of the payment.
Body parameterDescription
NoneThis endpoint does not require path parameters.

​
Request

curl --request GET \
    --url https://api-sandbox.superbank.co/v1/payments/6c7484fd-405d-4681-ba36-773b2ade1aae \
    --header 'X-Api-Key: sb_test_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"
}