Skip to content

Create a Checkout

When a Payer wants to pay, your server creates a Checkout and redirects them to its link.

Terminal window
curl https://api.voltpay.space/v1/checkouts \
-H "Authorization: Bearer $VOLTPAY_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"reference": "ORDER-1042",
"amount": "50.00",
"success_url": "https://shop.example/orders/1042"
}'
Field Required Meaning
reference Yes Your id for this payment, 1 to 64 characters. Unique per Mode.
amount Yes USD as a decimal string, up to six decimals, from 0.01. Each coin counts as 1 USD.
network, coin No Narrow the key’s Pairs. Leave both out and the Payer chooses.
customer_reference No Your id for the Payer, up to 128 characters. It comes back on the Payment.
expires_in No Lifetime in seconds, 900 to 1800. Default 1800.
success_url, cancel_url No Where the page sends the Payer after paying, or after giving up.

201 Created answers with the Checkout:

{
"id": "chk_01J9…",
"reference": "ORDER-1042",
"url": "https://pay.voltpay.space/c/8sJk2Qm4Tz",
"status": "open",
"amount": "50.00",
"pairs": [{ "network": "tron", "coin": "usdt" }],
"payment": null,
"expires_at": "2026-11-06T13:34:56Z",
"created_at": "2026-11-06T13:04:56Z"
}
HTTP/1.1 303 See Other
Location: https://pay.voltpay.space/c/8sJk2Qm4Tz
  • The page shows the address, the amount and a QR code, in English, Hindi or Simplified Chinese.
  • It refuses to load in an iframe. Open it as a top-level page.

Show these as “method unavailable”, not as a crash. No Checkout exists and no Payer saw a broken page.

Answer Why Fix
402 BALANCE_EXHAUSTED The Prepaid Balance cannot cover the Hold. Recharge.
422 NO_ADDRESS_FOR_PAIR No Pair on offer has a Receive Address. Add one at the error’s fix_url.
503 PAIR_AT_CAPACITY Every Tag Digit on the Pair is in use. Add Receive Addresses.
503 PAIR_PAUSED VoltPay has paused the Pair. Wait, or offer another Pair.
403 CHECKOUT_LIMIT_EXCEEDED The amount is above your limit. Split it, or write to support.

Every code is in Errors and retries.

Request Does
GET /v1/checkouts/{id} Reads a Checkout with its Payment.
GET /v1/checkouts?reference=ORDER-1042 Finds a Checkout by your reference.
POST /v1/checkouts/{id}/cancel Cancels an open Checkout. One whose money has been seen cannot be cancelled.
GET /v1/payments Lists Payments, newest first. Run it after an outage.

Create a key under Developers, then Keys. Each key carries its Mode (gw_test_… or gw_live_…), its Pairs, a Callback Endpoint and an optional IP allowlist.

  • The key decides the Mode, never a parameter.
  • Server only. Never put a key in a browser, an app or a repository.
  • A leaked key cannot redirect money. A key cannot change addresses, keys or Callback Endpoints.
  • 300 requests a minute for each key, a starting value. Above it: 429 RATE_LIMITED.
  • Revoking stops API calls at once. Callbacks keep arriving.
  • JSON in and out, snake_case, times in RFC 3339 UTC.
  • Amounts are decimal strings. Never parse them as floats.
  • A list is {"data": [...], "has_more": true, "next_cursor": "…"}. Pass next_cursor as starting_after.
  • Ignore fields you do not know.