الفواتير
إنشاء الفواتير واسترجاعها وعرضها وإلغاؤها.
إنشاء فاتورة
POST /api/v1/invoices
| الحقل | النوع | الوصف |
|---|---|---|
amount | string | إلزامي. المبلغ بعملة USDT حتى 6 خانات عشرية. |
currency | string | اختياري. دائماً USDT. |
network | string | إلزامي. trc20 أو bep20. |
order_id | string | مرجع الطلب لديك (حتى 191 حرفاً). |
description | string | يظهر في صفحة الدفع. |
success_url / cancel_url | string | وجهة العميل بعد الدفع أو الإلغاء. |
metadata | object | حتى 20 زوج مفتاح/قيمة تُعاد في الـ Webhooks. |
expires_in | integer | مدة الصلاحية بالدقائق (5–1440). الافتراضي 30. |
lang | string | فرض لغة صفحة الدفع: en أو ar. |
customer_email | string | بريد العميل (اختياري). |
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 م