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.

  1. Add a payout address for each network you want in Wallets.
  2. Create an API key in Developers, and set your webhook URL there.
  3. Create an invoice and redirect the customer to its payUrl.
  4. Mark the order paid when you receive invoice.paid, and treat invoice.settled as 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
FieldTypeDescription
qv_test_...Test keyWorks right after sign-up. Creates and sees sandbox invoices only.
qv_live_...Live keyNeeds 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

FieldTypeDescription
amountstring, requiredAmount in USD, for example "25.50". Up to 6 decimals.
orderIdstringYour order reference, up to 100 characters. Sending the same orderId again returns the same invoice, so retries are safe.
descriptionstringShown to the customer, up to 200 characters.
callbackUrlURLWhere webhooks for this invoice are sent. Must be a public address.
returnUrlURLWhere the payment page sends the customer when they are done.
expiresInMinutesinteger5 to 1440. Default 60.
networkstringOptional preset, for example "BSC". Send together with coin.
coinstringOptional preset, for example "USDT". Without a preset the customer chooses.
Request
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"
  }'
Response 201
{
  "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

FieldTypeDescription
idstringInvoice id. Sandbox ids start with inv_test_.
orderIdstring | nullYour order reference.
testbooleantrue for sandbox invoices.
amountstringAmount due in USD.
currencystringAlways USD.
statusstringPENDING, PAID, PARTIAL or EXPIRED. See Statuses.
networkstring | nullNetwork code the customer chose, for example BSC.
coinstring | nullCoin symbol the customer chose, for example USDT.
addressstring | nullDeposit address for the chosen network and coin.
paidAmountstring | nullAmount that arrived, in coin units (1 unit = 1 USD).
feestringFee in USD for this invoice.
expiresAtISO dateAfter this time new payments are not expected.
paidAtISO date | nullWhen the payment was detected.
payUrlURLThe hosted payment page for this invoice.
settledbooleantrue once the funds were forwarded to your wallet.
sweepTxHashstring | nullTransaction that forwarded the funds.

Statuses

FieldTypeDescription
PENDINGopenWaiting for the customer to pay.
PAIDfinalThe full amount arrived and is confirmed. Ship the order.
PARTIALfinalThe invoice expired with less than the full amount. The part that arrived is still forwarded to you.
EXPIREDfinalNothing 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.

Request
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.

FieldTypeDescription
invoice.paideventThe full amount is confirmed on-chain.
invoice.partialeventThe invoice expired with part of the amount paid.
invoice.expiredeventThe invoice expired with nothing paid.
invoice.settledeventThe funds were forwarded to your wallet.
Body
{
  "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
  }
}
FieldTypeDescription
X-Gateway-EventheaderThe event name.
X-Gateway-TimestampheaderUnix time in seconds when the request was signed.
X-Gateway-SignatureheaderHex 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.

Node.js
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);
}
PHP
$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);
Python
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"
}
FieldTypeDescription
HTTP_ERROR400A field is missing or has the wrong format. The message says which.
INVALID_AMOUNT400Amount must be greater than zero.
AMOUNT_TOO_SMALL400Below your plan's minimum invoice amount.
DAILY_LIMIT400Would pass your plan's 24-hour limit.
NETWORK_AND_COIN400Send both network and coin, or neither.
COIN_NOT_AVAILABLE400That coin is not enabled on that network.
WALLET_NOT_SET409Add a payout address for an available network first.
INVALID_API_KEY401Missing or wrong API key.
PLAN_EXPIRED402Your plan has expired. Renew it to continue.
QUOTA_EXCEEDED409Invoice limit reached for this period of your plan.
INVOICE_NOT_FOUND404No invoice with that id or orderId for this key.
INVOICE_CLOSED409The invoice can no longer change.
RATE_LIMIT_EXCEEDED429Too many requests. Wait and retry.
NETWORK_UNAVAILABLE503No 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.