واجهة API لمدفوعات الكريبتو: مدفوعات من الخادم إلى الخادم
دليل واجهة API لمدفوعات الكريبتو: أنشئ دفعة من خادمك عبر POST /api/v1/payment واستلم redirectUrl والحالة النهائية عبر webhook. مع مثال كود عملي.
تتيح واجهة API لمدفوعات الكريبتو لخلفيتك إنشاء دفعة وتوجيه العميل إلى صفحة دفع مستضافة ومعرفة الحالة النهائية دون بناء بنية blockchain خاصة. تقدم Qvard هذا المسار بوصفه Host-to-Host API v1.
ماذا تفعل واجهة API لمدفوعات الكريبتو
تحوّل واجهة API لمدفوعات الكريبتو حدث الشراء على خادمك إلى طلب دفع. ترسل خلفيتك معرّف طلبك والمبلغ بعملتك (الدولار الأمريكي افتراضيًا)، فتعيد البوابة redirectUrl إلى صفحة الدفع المستضافة حيث يختار العميل الأصل والشبكة. تبقى العناوين والأسعار ومراقبة البلوكتشين على جانب البوابة.
شكل طلب v1 في Qvard
الاستدعاء طلب POST واحد إلى /api/v1/payment مع ترويسة x-api-key. يحمل الحقل id معرّف معاملتك الخاص، والحقل price المبلغ بالعملة التي يحددها الحقل currency الاختياري (ISO-4217، والدولار الأمريكي افتراضيًا). الحقل paymentSystemId اختياري ويحدد طريقة الدفع عند الحاجة. تعيد الاستجابة معرّف الدفع وredirectUrl.
x-api-key: sk_live_…
{
"id": "order_1024",
"price": 12499.00,
"currency": "INR",
"paymentSystemId": 12
}
// 201 Created
{
"data": {
"id": "8f3k2a1c",
"redirectUrl": "https://my.qvard.com/pay/8f3k2a1c"
},
"code": 201,
"message": "success",
"status": true
}من الخادم إلى الخادم، لا من المتصفح إلى البوابة
يُرسل الطلب من خلفيتك، فلا تصل مفاتيح API إلى المتصفح أبدًا. لا يرى العميل صفحة الدفع المستضافة إلا بعد توجيهه إليها. كما تتحقق من كل طلب على جانبك قبل إنشاء الدفعة.
تصل الحالة النهائية عبر webhook
تؤكد استجابة API إنشاء الدفعة، لا أنها دُفعت. تُسلَّم الحالة النهائية إلى عنوان webhook الخاص بك كطلب POST يحمل الحقلين id وstatus، لذلك يجب أن يعتمد منطق الطلب على الـwebhook.
ما الذي تتحقق منه قبل الإطلاق
احفظ معرّف الدفعة بجوار الطلب، واجعل معالج الـwebhook آمنًا عند تشغيله مرتين، واختبر المسار كاملًا بفاتورة تجريبية. استخدم المعرّف نفسه في كل طلب لطلب واحد حتى يمكن مطابقة الاستدعاءات المتكررة.
الرسوم والشبكات
معدل المعالجة الأساسي 1% لكل دفعة، ويتراجع بشكل فردي إلى 0.1% مع نمو حجم عملياتك. تُدفع رسوم الشبكة منفصلة على الشبكة التي يختارها العميل. تحتفظ صفحة الأسعار بالشروط الحالية.
FAQ
هل واجهة API لمدفوعات الكريبتو هي نفسها رابط الدفع؟
لا. رابط الدفع صفحة قابلة للمشاركة للمبيعات اليدوية. أما الواجهة فتنشئ الدفعة من نظامك وتعيد redirectUrl يتحكم فيه كودك.
هل أحتاج إلى تشغيل عقدة blockchain؟
لا. تراقب Qvard الشبكات وتبلغ عن الحالة النهائية عبر webhook، فلا تحتاج إلى تشغيل عقد أو ماسحات بنفسك.
بأي عملة يُحدد السعر؟
حقل price بالعملة التي يحددها حقل currency (مثل INR أو EUR)، وبالدولار الأمريكي إن لم يُذكر. يدفع العميل بالأصل والشبكة التي يختارها في صفحة الدفع.
هل يمكنني الاختبار قبل الإطلاق؟
نعم. أنشئ فاتورة تجريبية وسترى صفحة الدفع المستضافة نفسها التي سيراها عملاؤك.
