الفواتير

إنشاء الفواتير واسترجاعها وعرضها وإلغاؤها.

إنشاء فاتورة

POST /api/v1/invoices

الحقلالنوعالوصف
amountstringإلزامي. المبلغ بعملة USDT حتى 6 خانات عشرية.
currencystringاختياري. دائماً USDT.
networkstringإلزامي. trc20 أو bep20.
order_idstringمرجع الطلب لديك (حتى 191 حرفاً).
descriptionstringيظهر في صفحة الدفع.
success_url / cancel_urlstringوجهة العميل بعد الدفع أو الإلغاء.
metadataobjectحتى 20 زوج مفتاح/قيمة تُعاد في الـ Webhooks.
expires_inintegerمدة الصلاحية بالدقائق (5–1440). الافتراضي 30.
langstringفرض لغة صفحة الدفع: en أو ar.
customer_emailstringبريد العميل (اختياري).
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);

الاستجابة 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": []
}

اطلب دائماً من العميل إرسال قيمة pay_amount بالضبط، ففي وضع العنوان الثابت تحتوي على فرق فريد.

استرجاع فاتورة

GET /api/v1/invoices/{id}

عرض الفواتير

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' } });

إلغاء فاتورة

POST /api/v1/invoices/{id}/cancel

يمكن إلغاء الفواتير ذات الحالة pending فقط.

الحالات

pendingبانتظار الدفع.
partially_paidتم استلام مبلغ أقل من المطلوب (بعد احتساب هامش التسامح).
paidتم رصد المبلغ كاملاً، بانتظار التأكيدات.
confirmedنهائية. يمكنك تسليم الطلب بأمان.
overpaidتم استلام مبلغ أكبر من المطلوب وتأكيده.
expiredلم يتم الدفع في الوقت المحدد. يتم رصد المدفوعات المتأخرة ووضع علامة عليها.
cancelledتم إلغاؤها من قبلك.
تحتاج مساعدة؟ تواصل معنا آخر تحديث: 17 نوفمبر 2026 م