Skip to content

Read a Checkout, with its Payment

GET
/checkouts/{id}
curl --request GET \
--url https://api.voltpay.space/v1/checkouts/chk_01J9%E2%80%A6 \
--header 'Authorization: Bearer <token>'

The answer to “did this get paid?” when a Callback is in doubt.

id
required
string

Example

chk_01J9…

The Checkout.

Media typeapplication/json
object
id
required
string
reference
required

The Merchant’s own identifier for a Checkout, unique per Merchant and Mode.

string
>= 1 characters <= 64 characters
url
required

The Checkout Link. It carries only an opaque token.

string format: uri
status
required

open can become paid, expired or cancelled. expired can still become paid within the Late Window.

string
Allowed values: open paid expired cancelled
amount
required

An amount in USD. Each Coin counts as 1 USD.

string
/^[0-9]+(\.[0-9]+)?$/
customer_reference
string | null
pairs
required

The Pairs on offer, fixed at creation.

Array<object>

One Network with one Coin.

object
network
required

One blockchain. Test mode uses the test Network codes.

string
Allowed values: tron bsc ethereum arbitrum solana base polygon optimism avalanche tron_nile bsc_testnet ethereum_sepolia arbitrum_sepolia solana_devnet
coin
required

The coin, identified on-chain by its contract and never by this symbol.

string
Allowed values: usdt usdc
payment
One of:
object
id
required

Derived from the Transfer, so one Transfer can never become two Payments.

string
status
required

seen may still be reversed. confirmed is Final or accepted early. reversed disappeared after being confirmed.

string
Allowed values: seen confirmed reversed
checkout_id
required
string
reference
required

The Merchant’s own identifier for a Checkout, unique per Merchant and Mode.

string
>= 1 characters <= 64 characters
customer_reference
required
string | null
requested_amount
required

An amount in USD. Each Coin counts as 1 USD.

string
/^[0-9]+(\.[0-9]+)?$/
amount
required

What actually arrived, kept exactly. The Merchant credits this.

string
/^[0-9]+(\.[0-9]+)?$/
amount_base_units
required

An on-chain amount in integer base units, as a string because it can exceed any JSON number.

string
/^[0-9]+$/
decimals
required

The Coin’s decimals on this Network. BSC uses 18, most others 6.

integer
match_result
required

How the amount that arrived compares with the Checkout.

string
Allowed values: exact under over late
matched_by
required

The evidence that matched the Transfer to the Checkout. A sender or transaction hash a Payer posted is never evidence.

string
Allowed values: exact_amount reservation tag_digits late manual
network
required

One blockchain. Test mode uses the test Network codes.

string
Allowed values: tron bsc ethereum arbitrum solana base polygon optimism avalanche tron_nile bsc_testnet ethereum_sepolia arbitrum_sepolia solana_devnet
coin
required

The coin, identified on-chain by its contract and never by this symbol.

string
Allowed values: usdt usdc
contract
required

The Coin’s contract on this Network.

string
address
required

The Receive Address the money went to.

string
address_name
required
string
from
required

The on-chain sender.

string
tx_hash
required
string
log_index
required
integer
block_number
required
integer format: int64
confirmed_by
required
One of:

final met the Network’s Confirmation Rule. early used the faster rule under the Early Limit.

string
Allowed values: final early
fee
required
One of:

An exact decimal amount. Never parse it into a float.

string
/^[0-9]+(\.[0-9]+)?$/
confirmed_at
required
string | null format: date-time
expires_at
required
string format: date-time
created_at
required
string format: date-time

Example

{
"id": "chk_01J9…",
"reference": "DEP20261106123456",
"url": "https://pay.voltpay.space/c/8sJk2Qm4Tz",
"status": "open",
"amount": "50.00",
"pairs": [
{
"network": "tron",
"coin": "usdt"
}
],
"expires_at": "2026-11-06T13:34:56Z",
"created_at": "2026-11-06T13:04:56Z"
}

INVALID_API_KEY: the key is missing, wrong or revoked.

Media typeapplication/json
object
error
required
object
code
required

The stable identifier a client branches on.

string
Allowed values: INVALID_API_KEY BALANCE_EXHAUSTED PAIR_NOT_ALLOWED MERCHANT_SUSPENDED CHECKOUT_LIMIT_EXCEEDED CHECKOUT_NOT_FOUND PAYMENT_NOT_FOUND REFERENCE_ALREADY_USED IDEMPOTENCY_KEY_REUSED REQUEST_IN_PROGRESS CHECKOUT_NOT_OPEN NO_ADDRESS_FOR_PAIR VALIDATION_ERROR RATE_LIMITED INTERNAL PAIR_AT_CAPACITY PAIR_PAUSED TRY_AGAIN
message
required

For people. May be reworded, so never branch on it.

string
request_id
required
string
details

More about the failure. For VALIDATION_ERROR, a map of field name to reason.

object
key
additional properties
any
max_checkout_micro

Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.

integer format: int64

Examples

Exampledefault
{
"error": {
"code": "INVALID_API_KEY",
"message": "The API key is missing, wrong or revoked.",
"request_id": "req_01J9…"
}
}

MERCHANT_SUSPENDED: Staff have suspended the Merchant.

Media typeapplication/json
object
error
required
object
code
required

The stable identifier a client branches on.

string
Allowed values: INVALID_API_KEY BALANCE_EXHAUSTED PAIR_NOT_ALLOWED MERCHANT_SUSPENDED CHECKOUT_LIMIT_EXCEEDED CHECKOUT_NOT_FOUND PAYMENT_NOT_FOUND REFERENCE_ALREADY_USED IDEMPOTENCY_KEY_REUSED REQUEST_IN_PROGRESS CHECKOUT_NOT_OPEN NO_ADDRESS_FOR_PAIR VALIDATION_ERROR RATE_LIMITED INTERNAL PAIR_AT_CAPACITY PAIR_PAUSED TRY_AGAIN
message
required

For people. May be reworded, so never branch on it.

string
request_id
required
string
details

More about the failure. For VALIDATION_ERROR, a map of field name to reason.

object
key
additional properties
any
max_checkout_micro

Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.

integer format: int64

Examples

Exampledefault
{
"error": {
"code": "MERCHANT_SUSPENDED",
"message": "This account is suspended. Contact support.",
"request_id": "req_01J9…"
}
}

CHECKOUT_NOT_FOUND: no such Checkout.

Media typeapplication/json
object
error
required
object
code
required

The stable identifier a client branches on.

string
Allowed values: INVALID_API_KEY BALANCE_EXHAUSTED PAIR_NOT_ALLOWED MERCHANT_SUSPENDED CHECKOUT_LIMIT_EXCEEDED CHECKOUT_NOT_FOUND PAYMENT_NOT_FOUND REFERENCE_ALREADY_USED IDEMPOTENCY_KEY_REUSED REQUEST_IN_PROGRESS CHECKOUT_NOT_OPEN NO_ADDRESS_FOR_PAIR VALIDATION_ERROR RATE_LIMITED INTERNAL PAIR_AT_CAPACITY PAIR_PAUSED TRY_AGAIN
message
required

For people. May be reworded, so never branch on it.

string
request_id
required
string
details

More about the failure. For VALIDATION_ERROR, a map of field name to reason.

object
key
additional properties
any
max_checkout_micro

Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.

integer format: int64

Examples

Exampledefault
{
"error": {
"code": "CHECKOUT_NOT_FOUND",
"message": "No Checkout has that id.",
"request_id": "req_01J9…"
}
}

RATE_LIMITED: back off, per Retry-After.

Media typeapplication/json
object
error
required
object
code
required

The stable identifier a client branches on.

string
Allowed values: INVALID_API_KEY BALANCE_EXHAUSTED PAIR_NOT_ALLOWED MERCHANT_SUSPENDED CHECKOUT_LIMIT_EXCEEDED CHECKOUT_NOT_FOUND PAYMENT_NOT_FOUND REFERENCE_ALREADY_USED IDEMPOTENCY_KEY_REUSED REQUEST_IN_PROGRESS CHECKOUT_NOT_OPEN NO_ADDRESS_FOR_PAIR VALIDATION_ERROR RATE_LIMITED INTERNAL PAIR_AT_CAPACITY PAIR_PAUSED TRY_AGAIN
message
required

For people. May be reworded, so never branch on it.

string
request_id
required
string
details

More about the failure. For VALIDATION_ERROR, a map of field name to reason.

object
key
additional properties
any
max_checkout_micro

Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.

integer format: int64

Examples

Exampledefault
{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Wait for the time in Retry-After, then try again.",
"request_id": "req_01J9…"
}
}
Retry-After
integer
>= 1

Seconds to wait before trying again.

INTERNAL: an unexpected failure. Quote request_id when reporting it.

Media typeapplication/json
object
error
required
object
code
required

The stable identifier a client branches on.

string
Allowed values: INVALID_API_KEY BALANCE_EXHAUSTED PAIR_NOT_ALLOWED MERCHANT_SUSPENDED CHECKOUT_LIMIT_EXCEEDED CHECKOUT_NOT_FOUND PAYMENT_NOT_FOUND REFERENCE_ALREADY_USED IDEMPOTENCY_KEY_REUSED REQUEST_IN_PROGRESS CHECKOUT_NOT_OPEN NO_ADDRESS_FOR_PAIR VALIDATION_ERROR RATE_LIMITED INTERNAL PAIR_AT_CAPACITY PAIR_PAUSED TRY_AGAIN
message
required

For people. May be reworded, so never branch on it.

string
request_id
required
string
details

More about the failure. For VALIDATION_ERROR, a map of field name to reason.

object
key
additional properties
any
max_checkout_micro

Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.

integer format: int64

Examples

Exampledefault
{
"error": {
"code": "INTERNAL",
"message": "Something went wrong on our side. Quote the request id if this continues.",
"request_id": "req_01J9…"
}
}

TRY_AGAIN: a time limit cut the request short and nothing was committed.

Media typeapplication/json
object
error
required
object
code
required

The stable identifier a client branches on.

string
Allowed values: INVALID_API_KEY BALANCE_EXHAUSTED PAIR_NOT_ALLOWED MERCHANT_SUSPENDED CHECKOUT_LIMIT_EXCEEDED CHECKOUT_NOT_FOUND PAYMENT_NOT_FOUND REFERENCE_ALREADY_USED IDEMPOTENCY_KEY_REUSED REQUEST_IN_PROGRESS CHECKOUT_NOT_OPEN NO_ADDRESS_FOR_PAIR VALIDATION_ERROR RATE_LIMITED INTERNAL PAIR_AT_CAPACITY PAIR_PAUSED TRY_AGAIN
message
required

For people. May be reworded, so never branch on it.

string
request_id
required
string
details

More about the failure. For VALIDATION_ERROR, a map of field name to reason.

object
key
additional properties
any
max_checkout_micro

Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.

integer format: int64

Examples

Exampledefault
{
"error": {
"code": "TRY_AGAIN",
"message": "Nothing was committed. Try the request again.",
"request_id": "req_01J9…"
}
}
Retry-After
integer
>= 1

Seconds to wait before trying again.