Create a Checkout
When a Payer wants to pay, your server creates a Checkout and redirects them to its link.
Create
Section titled “Create”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"}Redirect the Payer
Section titled “Redirect the Payer”HTTP/1.1 303 See OtherLocation: 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.
When a Checkout cannot open
Section titled “When a Checkout cannot open”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.
Read, find, cancel
Section titled “Read, find, cancel”| 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. |
API Keys
Section titled “API Keys”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.
Conventions
Section titled “Conventions”- 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": "…"}. Passnext_cursorasstarting_after. - Ignore fields you do not know.