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

  1. Your server creates an invoice and gets a pay_url.
  2. 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.
  3. 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.
  4. Once the transaction reaches the required number of confirmations, the invoice moves to paid and a notification is sent to your webhook.

Create an invoice

POST/api/v1/invoices
ParameterTypeDescription
amountstringRequired. Amount in USD, from 0.5 to 1,000,000. For example, "25.00".
order_idstringYour order number (up to 128 characters). Returned in the webhook.
descriptionstringDescription shown to the customer (up to 256 characters).
networkstringNetwork code (see below), if the customer shouldn't choose the currency.
success_urlstringWhere to send the customer after payment. Defaults to the return URL in your store settings.
fail_urlstringWhere 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

GET/api/v1/invoices/:id

Returns the invoice object. Useful for checking the status if a webhook didn't arrive.

List store networks

GET/api/v1/networks
{ "items": [ { "code": "USDT_TRC20", "asset": "USDT", "chain": "TRON", "standard": "TRC20",
               "label": "USDT · TRC20", "confirmations": 1, "memo": false } ] }

Invoice object

FieldDescription
idInvoice ID
statusStatus
amount_usdThe USD price you passed in
amount_to_pay_usdWhat the customer pays: price + service fee
fee_percentFee rate for this invoice, %
networkSelected network or null
addressStore wallet the transfer is expected at
amountExact crypto amount the customer must send
receivedAmount actually received
tx_hash, tx_urlTransaction hash and block explorer link
confirmationsNumber of confirmations
created_at, expires_at, paid_atTime in Unix seconds
pay_urlPayment page link

Statuses

createdInvoice created; the customer hasn't picked a currency yet. The link is valid for 24 hours.
waitingCurrency selected, rate locked; waiting for the transfer (30 minutes).
confirmingTransaction found; waiting for the required number of confirmations.
paidPaid. Webhook sent.
expiredTime ran out. If the transfer arrives within 2 hours of expiry, the invoice still becomes paid.

Network codes

CodeCurrencyConfirmations
USDT_TRC20USDT · TRON1
USDT_BEP20USDT · BNB Smart Chain5
USDT_ERC20USDT · Ethereum3
USDT_TONUSDT · TON1
USDT_SOLUSDT · Solana1
USDT_POLYGONUSDT · Polygon10
USDT_ARBITRUMUSDT · Arbitrum One3
USDT_BASEUSDT · Base3
USDC_ERC20USDC · Ethereum3
USDC_BEP20USDC · BNB Smart Chain5
USDC_SOLUSDC · Solana1
USDC_POLYGONUSDC · Polygon10
USDC_ARBITRUMUSDC · Arbitrum One3
USDC_BASEUSDC · Base3
BTCBitcoin1
ETHEthereum3
TONToncoin (with comment)1
SOLSolana1
LTCLitecoin2
TRXTRON1
BNBBNB Smart Chain5

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

400Invalid parameters: bad amount, network not available for the store, or store disabled
401Invalid or missing API key
402The merchant's balance doesn't cover the fee for this invoice — top up the balance in the dashboard
404Invoice not found
503Exchange rate temporarily unavailable — retry the request