Create a Checkout
const url = 'https://api.voltpay.space/v1/checkouts';const options = { method: 'POST', headers: { 'Idempotency-Key': '6c1f4a8e-2d3b-4f7e-9a11-0c5e8b7d2f10', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"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"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”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-0c5e8b7d2f10Request Bodyrequired
Section titled “Request Bodyrequired”object
The Merchant’s own identifier for a Checkout, unique per Merchant and Mode.
Example
DEP20261106123456An amount in USD. Each Coin counts as 1 USD.
Example
50.00Narrows the Pairs on offer. Must be within the key’s Pairs.
Narrows the Pairs on offer. Must be within the key’s Pairs.
An opaque string the Merchant uses to identify the person paying.
The Checkout’s lifetime in seconds.
Where the page returns the Payer after payment. A convenience, never a proof of payment.
Where the page returns a Payer who gives up.
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"}Responses
Section titled “Responses”The Checkout was created.
object
The Merchant’s own identifier for a Checkout, unique per Merchant and Mode.
The Checkout Link. It carries only an opaque token.
open can become paid, expired or cancelled. expired can still become paid within the Late Window.
An amount in USD. Each Coin counts as 1 USD.
The Pairs on offer, fixed at creation.
One Network with one Coin.
object
One blockchain. Test mode uses the test Network codes.
The coin, identified on-chain by its contract and never by this symbol.
object
Derived from the Transfer, so one Transfer can never become two Payments.
seen may still be reversed. confirmed is Final or accepted early. reversed disappeared after being confirmed.
The Merchant’s own identifier for a Checkout, unique per Merchant and Mode.
An amount in USD. Each Coin counts as 1 USD.
What actually arrived, kept exactly. The Merchant credits this.
An on-chain amount in integer base units, as a string because it can exceed any JSON number.
The Coin’s decimals on this Network. BSC uses 18, most others 6.
How the amount that arrived compares with the Checkout.
The evidence that matched the Transfer to the Checkout. A sender or transaction hash a Payer posted is never evidence.
One blockchain. Test mode uses the test Network codes.
The coin, identified on-chain by its contract and never by this symbol.
The Coin’s contract on this Network.
The Receive Address the money went to.
The on-chain sender.
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.
object
object
The stable identifier a client branches on.
For people. May be reworded, so never branch on it.
More about the failure. For VALIDATION_ERROR, a map of field name to reason.
object
Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.
Examples
{ "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.
object
object
The stable identifier a client branches on.
For people. May be reworded, so never branch on it.
More about the failure. For VALIDATION_ERROR, a map of field name to reason.
object
Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.
Examples
{ "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.
object
object
The stable identifier a client branches on.
For people. May be reworded, so never branch on it.
More about the failure. For VALIDATION_ERROR, a map of field name to reason.
object
Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.
Examples
{ "error": { "code": "PAIR_NOT_ALLOWED", "message": "USDC on TRON is outside this API Key's Pairs.", "request_id": "req_01J9…" }}{ "error": { "code": "MERCHANT_SUSPENDED", "message": "This account is suspended. Contact support.", "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.
object
object
The stable identifier a client branches on.
For people. May be reworded, so never branch on it.
More about the failure. For VALIDATION_ERROR, a map of field name to reason.
object
Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.
Examples
{ "error": { "code": "REFERENCE_ALREADY_USED", "message": "A Checkout with this Reference already exists.", "request_id": "req_01J9…" }}{ "error": { "code": "IDEMPOTENCY_KEY_REUSED", "message": "This Idempotency-Key was used with a different request body.", "request_id": "req_01J9…" }}{ "error": { "code": "REQUEST_IN_PROGRESS", "message": "The first request with this Idempotency-Key is still running.", "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.
Tells the Merchant how to fix it. Treat this as “method unavailable”, not as a crash.
object
object
The stable identifier a client branches on.
For people. May be reworded, so never branch on it.
More about the failure. For VALIDATION_ERROR, a map of field name to reason.
object
Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.
One blockchain. Test mode uses the test Network codes.
The coin, identified on-chain by its contract and never by this symbol.
The Merchant Panel’s address form, filled in for this Pair.
object
object
The stable identifier a client branches on.
For people. May be reworded, so never branch on it.
More about the failure. For VALIDATION_ERROR, a map of field name to reason.
object
Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.
object
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…" }}{ "error": { "code": "VALIDATION_ERROR", "message": "Some fields are not valid.", "request_id": "req_01J9…", "details": { "expires_in": "Must be at least 900." } }}RATE_LIMITED: back off, per Retry-After.
object
object
The stable identifier a client branches on.
For people. May be reworded, so never branch on it.
More about the failure. For VALIDATION_ERROR, a map of field name to reason.
object
Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.
Examples
{ "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait for the time in Retry-After, then try again.", "request_id": "req_01J9…" }}Headers
Section titled “Headers”Seconds to wait before trying again.
INTERNAL: an unexpected failure. Quote request_id when reporting it.
object
object
The stable identifier a client branches on.
For people. May be reworded, so never branch on it.
More about the failure. For VALIDATION_ERROR, a map of field name to reason.
object
Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.
Examples
{ "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.
object
object
The stable identifier a client branches on.
For people. May be reworded, so never branch on it.
More about the failure. For VALIDATION_ERROR, a map of field name to reason.
object
Only with CHECKOUT_LIMIT_EXCEEDED. The largest Checkout the Merchant may create now, in micro-USD.
Examples
{ "error": { "code": "PAIR_AT_CAPACITY", "message": "Every Tag Digit is in use for USDT on TRON. Add Receive Addresses.", "request_id": "req_01J9…" }}{ "error": { "code": "PAIR_PAUSED", "message": "USDT on TRON is paused for now.", "request_id": "req_01J9…" }}{ "error": { "code": "TRY_AGAIN", "message": "Nothing was committed. Try the request again.", "request_id": "req_01J9…" }}Headers
Section titled “Headers”Seconds to wait before trying again.