API documentation
Everything you need to take crypto payments with Qavera: create an invoice, send your customer to the payment page, and get a signed webhook when the money is in your wallet.
Overview
The API is JSON over HTTPS. The base URL is https://qavera.top/api. Amounts are strings in US dollars with up to 6 decimals, and every supported coin is a USD stablecoin counted 1:1.
- Add a payout address for each network you want in Wallets.
- Create an API key in Developers, and set your webhook URL there.
- Create an invoice and redirect the customer to its
payUrl. - Mark the order paid when you receive
invoice.paid, and treatinvoice.settledas the moment the funds reached your wallet.
Qavera never holds your money. Each invoice has its own deposit address; after confirmations, one on-chain transaction sends the payment to your wallet and the fee, if your plan has one, to us.
Authentication
Send your API key as a bearer token, or in the X-API-Key header. Keys are secret: use them only from your server.
Authorization: Bearer qv_live_xxxxxxxxxxxxxxxx| Field | Type | Description |
|---|---|---|
| qv_test_... | Test key | Works right after sign-up. Creates and sees sandbox invoices only. |
| qv_live_... | Live key | Needs a verified email. Creates and sees real invoices only. |
A missing or wrong key returns 401 with code INVALID_API_KEY.
Sandbox
With a test key every call works the same as live, but invoices never touch a blockchain. Their ids start with inv_test_, they use none of your plan quota, and webhooks carry "test": true. Settle them with the simulate endpoint or the buttons on their payment page.
Create an invoice
POST/api/v1/invoices
| Field | Type | Description |
|---|---|---|
| amount | string, required | Amount in USD, for example "25.50". Up to 6 decimals. |
| orderId | string | Your order reference, up to 100 characters. Sending the same orderId again returns the same invoice, so retries are safe. |
| description | string | Shown to the customer, up to 200 characters. |
| callbackUrl | URL | Where webhooks for this invoice are sent. Must be a public address. |
| returnUrl | URL | Where the payment page sends the customer when they are done. |
| expiresInMinutes | integer | 5 to 1440. Default 60. |
| network | string | Optional preset, for example "BSC". Send together with coin. |
| coin | string | Optional preset, for example "USDT". Without a preset the customer chooses. |
curl https://qavera.top/api/v1/invoices \
-H "Authorization: Bearer qv_live_..." \
-H "Content-Type: application/json" \
-d '{
"amount": "120",
"orderId": "A-1001",
"callbackUrl": "https://shop.example/qavera/webhook",
"returnUrl": "https://shop.example/orders/A-1001"
}'{
"id": "inv_3f9c0a1b2c3d4e5f60718293",
"orderId": "A-1001",
"test": false,
"amount": "120",
"currency": "USD",
"status": "PENDING",
"network": null,
"coin": null,
"address": null,
"paidAmount": null,
"fee": "1.2",
"expiresAt": "2026-11-18T12:00:00.000Z",
"payUrl": "https://qavera.top/pay/inv_3f9c0a1b2c3d4e5f60718293",
"settled": false,
"sweepTxHash": null
}The fee is fixed when the invoice is created, from your plan's fee ranges (percentage with a minimum and a maximum).
The invoice object
| Field | Type | Description |
|---|---|---|
| id | string | Invoice id. Sandbox ids start with inv_test_. |
| orderId | string | null | Your order reference. |
| test | boolean | true for sandbox invoices. |
| amount | string | Amount due in USD. |
| currency | string | Always USD. |
| status | string | PENDING, PAID, PARTIAL or EXPIRED. See Statuses. |
| network | string | null | Network code the customer chose, for example BSC. |
| coin | string | null | Coin symbol the customer chose, for example USDT. |
| address | string | null | Deposit address for the chosen network and coin. |
| paidAmount | string | null | Amount that arrived, in coin units (1 unit = 1 USD). |
| fee | string | Fee in USD for this invoice. |
| expiresAt | ISO date | After this time new payments are not expected. |
| paidAt | ISO date | null | When the payment was detected. |
| payUrl | URL | The hosted payment page for this invoice. |
| settled | boolean | true once the funds were forwarded to your wallet. |
| sweepTxHash | string | null | Transaction that forwarded the funds. |
Statuses
| Field | Type | Description |
|---|---|---|
| PENDING | open | Waiting for the customer to pay. |
| PAID | final | The full amount arrived and is confirmed. Ship the order. |
| PARTIAL | final | The invoice expired with less than the full amount. The part that arrived is still forwarded to you. |
| EXPIRED | final | Nothing arrived in time. A full payment that arrives within 24 hours after expiry is still accepted and turns the invoice PAID. |
Payment page
Redirect the customer to payUrl. They pick a network and a coin, then see the address, a QR code and a countdown. The page updates by itself and offers a button back to your returnUrl. You can also preset network and coin when creating the invoice.
Look up invoices
Use these to confirm a status from your server, for example before shipping or if a webhook was missed.
GET/api/v1/invoices/{id}
GET/api/v1/invoices?orderId=A-1001
GET/api/v1/invoices?take=50&skip=0
The first two return one invoice object. Without orderId you get your latest invoices, newest first, up to 100 per page. A test key only sees sandbox invoices and a live key only live ones.
curl https://qavera.top/api/v1/invoices?orderId=A-1001 \
-H "Authorization: Bearer qv_live_..."Webhooks
When an invoice changes, Qavera sends a POST with a JSON body to its callbackUrl. Events of one invoice arrive in order.
| Field | Type | Description |
|---|---|---|
| invoice.paid | event | The full amount is confirmed on-chain. |
| invoice.partial | event | The invoice expired with part of the amount paid. |
| invoice.expired | event | The invoice expired with nothing paid. |
| invoice.settled | event | The funds were forwarded to your wallet. |
{
"event": "invoice.paid",
"test": false,
"invoice": {
"id": "inv_3f9c0a1b2c3d4e5f60718293",
"orderId": "A-1001",
"test": false,
"amount": "120",
"currency": "USD",
"network": "BSC",
"coin": "USDT",
"paidAmount": "120",
"fee": "1.2",
"status": "PAID",
"address": "0x9f2a4be17c03d5a8e9b61f0c7d2e48a1b3c5c41e",
"paidAt": "2026-11-18T11:14:03.000Z",
"sweepTxHash": null
}
}| Field | Type | Description |
|---|---|---|
| X-Gateway-Event | header | The event name. |
| X-Gateway-Timestamp | header | Unix time in seconds when the request was signed. |
| X-Gateway-Signature | header | Hex HMAC-SHA256 of timestamp + "." + raw body, keyed with your webhook secret. |
Answer with any 2xx within 10 seconds. Anything else is retried with growing delays (30 seconds, then 1, 2, 4 minutes and so on, up to 6 hours apart), 8 attempts in total. Handle duplicates by invoice id and event: the same event can arrive twice.
Verify signatures
Always check the signature on the raw request body before trusting a webhook, and reject timestamps older than 5 minutes. Your webhook secret is in Developers.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(secret, rawBody, timestamp, signature) {
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
const given = Buffer.from(signature, "hex");
return given.length === expected.length && timingSafeEqual(given, expected);
}$body = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_GATEWAY_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_GATEWAY_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $ts . '.' . $body, $secret);
if (abs(time() - (int) $ts) > 300 || !hash_equals($expected, $sig)) {
http_response_code(400);
exit;
}
$event = json_decode($body, true);import hmac, hashlib, time
def verify(secret: str, raw_body: bytes, timestamp: str, signature: str) -> bool:
if abs(time.time() - int(timestamp)) > 300:
return False
expected = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)Simulate payments
POST/api/v1/invoices/{id}/simulate
Test keys only. Body {"outcome": "paid"}, "partial" (half the amount) or "expired". Returns the updated invoice and fires the same webhooks a live invoice would; paid and partial are followed by invoice.settled.
curl -X POST https://qavera.top/api/v1/invoices/inv_test_.../simulate \
-H "Authorization: Bearer qv_test_..." \
-H "Content-Type: application/json" \
-d '{"outcome":"paid"}'Networks and coins
GET/api/networks
Public. Lists the networks that are live right now with their coins (symbol, contract, decimals). Use the code and coin symbol when presetting an invoice. Live service health is on the status page.
Errors
Errors use HTTP status codes and a JSON body with a stable code you can match on.
{
"statusCode": 400,
"code": "AMOUNT_TOO_SMALL",
"message": "The minimum invoice amount is 10 USD",
"requestId": "6f1c2b0e-...",
"timestamp": "2026-11-18T11:00:00.000Z",
"path": "/api/v1/invoices"
}| Field | Type | Description |
|---|---|---|
| HTTP_ERROR | 400 | A field is missing or has the wrong format. The message says which. |
| INVALID_AMOUNT | 400 | Amount must be greater than zero. |
| AMOUNT_TOO_SMALL | 400 | Below your plan's minimum invoice amount. |
| DAILY_LIMIT | 400 | Would pass your plan's 24-hour limit. |
| NETWORK_AND_COIN | 400 | Send both network and coin, or neither. |
| COIN_NOT_AVAILABLE | 400 | That coin is not enabled on that network. |
| WALLET_NOT_SET | 409 | Add a payout address for an available network first. |
| INVALID_API_KEY | 401 | Missing or wrong API key. |
| PLAN_EXPIRED | 402 | Your plan has expired. Renew it to continue. |
| QUOTA_EXCEEDED | 409 | Invoice limit reached for this period of your plan. |
| INVOICE_NOT_FOUND | 404 | No invoice with that id or orderId for this key. |
| INVOICE_CLOSED | 409 | The invoice can no longer change. |
| RATE_LIMIT_EXCEEDED | 429 | Too many requests. Wait and retry. |
| NETWORK_UNAVAILABLE | 503 | No network is available right now. Retry later. |
Limits
- Invoices per period, minimum amount and 24-hour volume depend on your plan.
- Callback URLs must resolve to a public address; private and local addresses are refused.
- Public payment page endpoints are rate limited per IP. Back off on
429.
Questions about the API? Use the contacts at the bottom of this page.