Skip to content

Create a Checkout

POST
/checkouts
curl --request POST \
--url https://api.voltpay.space/v1/checkouts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 6c1f4a8e-2d3b-4f7e-9a11-0c5e8b7d2f10' \
--data '{ "reference": "DEP20261106123456", "amount": "50.00", "network": "tron", "coin": "usdt", "customer_reference": "user_8f21", "expires_in": 1800, "success_url": "https://merchant.example/deposit/done", "cancel_url": "https://merchant.example/deposit" }'

Opens a Checkout and returns its Checkout Link, which the Merchant’s server redirects the Payer to. The Pairs on offer are the API Key’s, narrowed by network and coin, and limited to Pairs with a Receive Address. A live Checkout takes a Hold from the Available Balance.

Idempotency-Key
string
<= 255 characters

Makes a retry safe. Stored for 24 hours with a fingerprint of the method, path and body. A repeat with the same fingerprint returns the first answer.

Example

6c1f4a8e-2d3b-4f7e-9a11-0c5e8b7d2f10
Media typeapplication/json
object
reference
required

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

string
>= 1 characters <= 64 characters

Example

DEP20261106123456
amount
required

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

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

Example

50.00
network

Narrows the Pairs on offer. Must be within the key’s Pairs.

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

Narrows the Pairs on offer. Must be within the key’s Pairs.

string
Allowed values: usdt usdc
customer_reference

An opaque string the Merchant uses to identify the person paying.

string
<= 128 characters
expires_in

The Checkout’s lifetime in seconds.

integer
default: 1800 >= 900 <= 1800
success_url

Where the page returns the Payer after payment. A convenience, never a proof of payment.

string format: uri
cancel_url

Where the page returns a Payer who gives up.

string format: uri

Example

{
"reference": "DEP20261106123456",
"amount": "50.00",
"network": "tron",
"coin": "usdt",
"customer_reference": "user_8f21",
"expires_in": 1800,
"success_url": "https://merchant.example/deposit/done",
"cancel_url": "https://merchant.example/deposit"
}

The Checkout was created.

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…"
}
}

BALANCE_EXHAUSTED: the Available Balance cannot cover this Checkout’s Hold. A Recharge restores service at once.

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": "BALANCE_EXHAUSTED",
"message": "Your Available Balance cannot cover this Checkout. Recharge to continue.",
"request_id": "req_01J9…"
}
}

PAIR_NOT_ALLOWED: the Pair is outside the key’s Pairs. 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

{
"error": {
"code": "PAIR_NOT_ALLOWED",
"message": "USDC on TRON is outside this API Key's Pairs.",
"request_id": "req_01J9…"
}
}

REFERENCE_ALREADY_USED: that Reference exists for this Merchant and Mode. IDEMPOTENCY_KEY_REUSED: the same key was used with a different body. REQUEST_IN_PROGRESS: the first request with this key is still running.

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

{
"error": {
"code": "REFERENCE_ALREADY_USED",
"message": "A Checkout with this Reference already exists.",
"request_id": "req_01J9…"
}
}

NO_ADDRESS_FOR_PAIR: no Pair on offer has a Receive Address, and no Checkout exists. VALIDATION_ERROR: per-field reasons are in details.

Media typeapplication/json
One of:

Tells the Merchant how to fix it. Treat this as “method unavailable”, not as a crash.

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
code
required
string
Allowed value: NO_ADDRESS_FOR_PAIR
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
fix_url
required

The Merchant Panel’s address form, filled in for this Pair.

string format: uri

Examples

{
"error": {
"code": "NO_ADDRESS_FOR_PAIR",
"message": "Add a wallet address for USDT on TRON to receive these payments.",
"network": "tron",
"coin": "usdt",
"fix_url": "https://app.voltpay.space/addresses/new?network=tron&coin=usdt",
"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…"
}
}

PAIR_AT_CAPACITY: every Tag Digit is in use, so add Receive Addresses. PAIR_PAUSED: Staff have paused the Pair. 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

{
"error": {
"code": "PAIR_AT_CAPACITY",
"message": "Every Tag Digit is in use for USDT on TRON. Add Receive Addresses.",
"request_id": "req_01J9…"
}
}
Retry-After
integer
>= 1

Seconds to wait before trying again.