Invoices
Create, retrieve, list and cancel invoices.
Create an invoice
POST /api/v1/invoices
| Field | Type | Description |
|---|---|---|
amount | string | Required. Amount in USDT, up to 6 decimals. |
currency | string | Optional. Always USDT. |
network | string | Required. trc20 or bep20. |
order_id | string | Your order reference (max 191 chars). |
description | string | Shown on the checkout page. |
success_url / cancel_url | string | Where to send the customer afterwards. |
metadata | object | Up to 20 key/value pairs returned in webhooks. |
expires_in | integer | Lifetime in minutes (5–1440). Default 30. |
lang | string | Force the checkout language: en or ar. |
customer_email | string | Optional customer e-mail. |
curl -X POST https://pay-test.qanawat.store/api/v1/invoices \
-H "Authorization: Bearer sk_test_your_secret_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1001" \
-d '{
"amount": "25.00",
"currency": "USDT",
"network": "trc20",
"order_id": "1001",
"description": "Order #1001",
"success_url": "https://shop.example.com/thanks",
"cancel_url": "https://shop.example.com/cart",
"metadata": {"customer_id": "42"},
"lang": "en"
}'<?php
require 'PaymentGateway.php';
$gateway = new PaymentGateway('sk_test_your_secret_key', 'https://pay-test.qanawat.store');
$invoice = $gateway->createInvoice([
'amount' => '25.00',
'currency' => 'USDT',
'network' => 'trc20',
'order_id' => '1001',
'success_url' => 'https://shop.example.com/thanks',
'cancel_url' => 'https://shop.example.com/cart',
], 'order-1001');
header('Location: ' . $invoice['checkout_url']);const res = await fetch('https://pay-test.qanawat.store/api/v1/invoices', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk_test_your_secret_key',
'Content-Type': 'application/json',
'Idempotency-Key': 'order-1001',
},
body: JSON.stringify({
amount: '25.00',
currency: 'USDT',
network: 'trc20',
order_id: '1001',
success_url: 'https://shop.example.com/thanks',
}),
});
const invoice = await res.json();
console.log(invoice.checkout_url);Response 201 Created:
{
"id": "inv_8c1k2m9q4w7e3r5t6y0u",
"object": "invoice",
"status": "pending",
"environment": "test",
"network": "trc20",
"currency": "USDT",
"amount": "25.000000",
"pay_amount": "25.000000",
"amount_paid": "0.000000",
"address": "TJ8w2sQYk6n8cW3nVvG6kP2cXxH9Lm4b7R",
"order_id": "1001",
"checkout_url": "https://pay-test.qanawat.store/pay/inv_8c1k2m9q4w7e3r5t6y0u",
"expires_at": "2026-01-01T12:30:00Z",
"created_at": "2026-01-01T12:00:00Z",
"transactions": []
}Always ask the customer to send exactly pay_amount. In static-address mode it contains a unique offset.
Retrieve an invoice
GET /api/v1/invoices/{id}
List invoices
GET /api/v1/invoices?status=&from=&to=&page=
curl "https://pay-test.qanawat.store/api/v1/invoices?status=confirmed&from=2026-01-01&page=1" -H "Authorization: Bearer sk_test_your_secret_key"$page = $gateway->listInvoices(['status' => 'confirmed', 'from' => '2026-01-01']);const res = await fetch('https://pay-test.qanawat.store/api/v1/invoices?status=confirmed', { headers: { Authorization: 'Bearer sk_test_your_secret_key' } });Cancel an invoice
POST /api/v1/invoices/{id}/cancel
Only pending invoices can be cancelled.
Statuses
pending | Waiting for payment. |
partially_paid | Less than the amount (minus tolerance) received. |
paid | Full amount detected, waiting for confirmations. |
confirmed | Final. Safe to fulfil the order. |
overpaid | More than the amount (plus tolerance) received and confirmed. |
expired | Not paid in time. Late payments are still detected and flagged. |
cancelled | Cancelled by you. |
Need help? Contact us
Last updated: Nov 17, 2026