Invoices

Create, retrieve, list and cancel invoices.

Create an invoice

POST /api/v1/invoices

FieldTypeDescription
amountstringRequired. Amount in USDT, up to 6 decimals.
currencystringOptional. Always USDT.
networkstringRequired. trc20 or bep20.
order_idstringYour order reference (max 191 chars).
descriptionstringShown on the checkout page.
success_url / cancel_urlstringWhere to send the customer afterwards.
metadataobjectUp to 20 key/value pairs returned in webhooks.
expires_inintegerLifetime in minutes (5–1440). Default 30.
langstringForce the checkout language: en or ar.
customer_emailstringOptional 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

pendingWaiting for payment.
partially_paidLess than the amount (minus tolerance) received.
paidFull amount detected, waiting for confirmations.
confirmedFinal. Safe to fulfil the order.
overpaidMore than the amount (plus tolerance) received and confirmed.
expiredNot paid in time. Late payments are still detected and flagged.
cancelledCancelled by you.
Need help? Contact us Last updated: Nov 17, 2026