API documentation
The API lets you create crypto payment invoices and receive payment notifications. All invoice amounts are set in US dollars, and the service works out the exact amount in the chosen cryptocurrency at the current rate. Funds go straight to the wallets configured in your store.
Base URL: https://example.com/api/v1. Requests and responses are JSON.
Authentication
Each store has its own API key — you'll find it in the dashboard under Stores → your store → API & webhook. Pass the key in a header:
Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxx
The X-Api-Key header is also supported. A key only grants access to its own store's invoices. Never use it on the front end.
Payment flow
- Your server creates an invoice and gets a
pay_url. - The customer opens the link and picks a currency (or you set it upfront with
network). From that moment the rate is locked for 30 minutes. - The customer sends the exact amount to the store's address. The amount is unique for each pending invoice (e.g.
25.0001), so the payment is matched to its invoice unambiguously. TON payments also use a comment. - Once the transaction reaches the required number of confirmations, the invoice moves to
paidand a notification is sent to your webhook.
Create an invoice
| Parameter | Type | Description |
|---|---|---|
amount | string | Required. Amount in USD, from 0.5 to 1,000,000. For example, "25.00". |
order_id | string | Your order number (up to 128 characters). Returned in the webhook. |
description | string | Description shown to the customer (up to 256 characters). |
network | string | Network code (see below), if the customer shouldn't choose the currency. |
success_url | string | Where to send the customer after payment. Defaults to the return URL in your store settings. |
fail_url | string | Where to send the customer if the payment window expires. Defaults to the failure URL in your store settings. |
Example request
curl -X POST https://example.com/api/v1/invoices \
-H "Authorization: Bearer sk_..." \
-H "Content-Type: application/json" \
-d '{"amount":"25.00","order_id":"1001","description":"Order #1001"}'
Response
{
"id": "aB3dE5fG7hJ9",
"status": "created",
"amount_usd": "25.00",
"amount_to_pay_usd": "25.25",
"fee_percent": 1,
"order_id": "1001",
"description": "Order #1001",
"network": null,
"address": null,
"amount": null,
"pay_url": "https://example.com/pay/aB3dE5fG7hJ9",
"created_at": 1794431718,
"expires_at": 1794518118
}
Retrieve an invoice
Returns the invoice object. Useful for checking the status if a webhook didn't arrive.
List store networks
{ "items": [ { "code": "USDT_TRC20", "asset": "USDT", "chain": "TRON", "standard": "TRC20",
"label": "USDT · TRC20", "confirmations": 1, "memo": false } ] }
Invoice object
| Field | Description |
|---|---|
id | Invoice ID |
status | Status |
amount_usd | The USD price you passed in |
amount_to_pay_usd | What the customer pays: price + service fee |
fee_percent | Fee rate for this invoice, % |
network | Selected network or null |
address | Store wallet the transfer is expected at |
amount | Exact crypto amount the customer must send |
received | Amount actually received |
tx_hash, tx_url | Transaction hash and block explorer link |
confirmations | Number of confirmations |
created_at, expires_at, paid_at | Time in Unix seconds |
pay_url | Payment page link |
Statuses
created | Invoice created; the customer hasn't picked a currency yet. The link is valid for 24 hours. |
waiting | Currency selected, rate locked; waiting for the transfer (30 minutes). |
confirming | Transaction found; waiting for the required number of confirmations. |
paid | Paid. Webhook sent. |
expired | Time ran out. If the transfer arrives within 2 hours of expiry, the invoice still becomes paid. |
Network codes
| Code | Currency | Confirmations |
|---|---|---|
USDT_TRC20 | USDT · TRON | 1 |
USDT_BEP20 | USDT · BNB Smart Chain | 5 |
USDT_ERC20 | USDT · Ethereum | 3 |
USDT_TON | USDT · TON | 1 |
USDT_SOL | USDT · Solana | 1 |
USDT_POLYGON | USDT · Polygon | 10 |
USDT_ARBITRUM | USDT · Arbitrum One | 3 |
USDT_BASE | USDT · Base | 3 |
USDC_ERC20 | USDC · Ethereum | 3 |
USDC_BEP20 | USDC · BNB Smart Chain | 5 |
USDC_SOL | USDC · Solana | 1 |
USDC_POLYGON | USDC · Polygon | 10 |
USDC_ARBITRUM | USDC · Arbitrum One | 3 |
USDC_BASE | USDC · Base | 3 |
BTC | Bitcoin | 1 |
ETH | Ethereum | 3 |
TON | Toncoin (with comment) | 1 |
SOL | Solana | 1 |
LTC | Litecoin | 2 |
TRX | TRON | 1 |
BNB | BNB Smart Chain | 5 |
Webhook
After payment, the service sends a POST to the store's webhook URL:
POST /your/webhook HTTP/1.1
Content-Type: application/json
X-Signature: 5d41402abc4b2a76b9719d911017c592...
{
"event": "invoice.paid",
"invoice": {
"id": "aB3dE5fG7hJ9",
"status": "paid",
"amount_usd": "25.00",
"order_id": "1001",
"network": "USDT_TRC20",
"amount": "25.0001",
"received": "25.0001",
"tx_hash": "b19fbeda...",
"paid_at": 1794433120
}
}
Respond with a 2xx code. On an error or timeout (10 s), delivery is retried up to 8 times with increasing delays: 1, 2, 4, 8… minutes.
Handle notifications idempotently, keyed by invoice.id.
Verifying signatures
X-Signature is the hex-encoded HMAC-SHA256 of the raw request body, keyed with the store's webhook secret.
Node.js
import crypto from "node:crypto";
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
const sig = crypto.createHmac("sha256", process.env.WEBHOOK_SECRET).update(req.body).digest("hex");
if (sig !== req.get("x-signature")) return res.sendStatus(401);
const { invoice } = JSON.parse(req.body);
// mark order invoice.order_id as paid
res.sendStatus(200);
});
PHP
$body = file_get_contents('php://input');
$sig = hash_hmac('sha256', $body, getenv('WEBHOOK_SECRET'));
if (!hash_equals($sig, $_SERVER['HTTP_X_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
$data = json_decode($body, true);
// $data['invoice']['order_id'] is paid
http_response_code(200);
Python
import hmac, hashlib
sig = hmac.new(WEBHOOK_SECRET.encode(), request.body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(sig, request.headers.get("X-Signature", "")):
return Response(status=401)
Errors
On error, the API returns an HTTP status code and JSON like {"detail": "error message"}.
400 | Invalid parameters: bad amount, network not available for the store, or store disabled |
401 | Invalid or missing API key |
402 | The merchant's balance doesn't cover the fee for this invoice — top up the balance in the dashboard |
404 | Invoice not found |
503 | Exchange rate temporarily unavailable — retry the request |