إنشاء دفعة كريبتو والحصول على redirectUrl
كيفية إنشاء دفعة كريبتو والحصول على redirectUrl في استدعاء API واحد: POST /api/v1/payment وترويسة x-api-key ومبلغ بعملتك (الدولار الأمريكي افتراضيًا) وتوجيه للدفع. مع مثال كامل.
إنشاء الدفعة والحصول على redirectUrl طلب واحد في Host-to-Host API v1 من Qvard. يشرح هذا الدليل حقول الطلب والاستجابة وكيفية توجيه العميل إلى صفحة الدفع بأمان.
حقول الطلب
أرسل طلب POST إلى /api/v1/payment مع ترويسة x-api-key. الحقل id هو معرّف معاملتك، والحقل price هو المبلغ بالعملة المحددة في currency (ISO-4217، والدولار الأمريكي افتراضيًا)، والحقل currency (مثل INR أو RUB أو EUR) اختياري، والحقل paymentSystemId اختياري. اجعل id فريدًا لكل طلب حتى تطابق الاستجابة مع سجلاتك. تُرفض العملة غير المدعومة بالرمز 422 unsupported_currency، وعدد المنازل العشرية الزائد لتلك العملة بالرمز 422 invalid_amount_precision، والعملة التي لا سعر صرف لها بالرمز 422 rate_unavailable.
قراءة الاستجابة
تحتوي الاستجابة على معرّف الدفعة وredirectUrl، وهو يشير إلى الصفحة المستضافة على https://my.qvard.com/pay/ متبوعًا بمعرّف الدفعة. احفظ القيمتين مع الطلب قبل توجيه العميل.
توجيه العميل
وجّه العميل إلى redirectUrl بتحويل HTTP عادي أو برابط في موقعك. في الصفحة المستضافة يختار العميل الأصل والشبكة ويرى المبلغ الدقيق بسعر صرف ثابت.
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
}الأخطاء وإعادة المحاولة
إذا فشل طلب فتحقق من سجلاتك قبل إعادة إرساله حتى لا يحصل طلب واحد على دفعتين. سجّل محتوى الاستجابة للدعم، ولا تعد المحاولة إلا بعد التأكد من عدم وجود دفعة لذلك الطلب.
أخطاء شائعة
لا تضع x-api-key في كود الواجهة الأمامية، ولا تعتبر التحويل تأكيدًا للدفع، ولا ترسل السعر بعملة غير العملة المحددة في الحقل currency. تصل الحالة النهائية دائمًا عبر webhook.
طلب إلكتروني خطوة بخطوة
عندما يضغط المشتري على الدفع يُنشئ خادمك الدفعة بمعرّف الطلب وإجمالي السلة، ثم يوجّه المشتري إلى redirectUrl. وعندما يبلغ الـwebhook بالدفع تضع علامة مدفوع على الطلب.
FAQ
هل يجب أن أرسل paymentSystemId؟
لا، هو اختياري. أرسله عندما تريد طريقة دفع محددة، وإلا تعرض الصفحة المستضافة الخيارات المتاحة.
هل يمكن إعادة استخدام redirectUrl لطلب آخر؟
لا. لكل دفعة redirectUrl خاص بها. أنشئ دفعة جديدة لكل طلب.
هل يمكن للعميل الدفع من رابط أرسلته بالبريد؟
نعم. redirectUrl صفحة HTTPS عادية فتعمل في البريد أو المحادثة. رابط الدفع بلا كود من لوحة التحكم ضمن خارطة الطريق.
ما المبلغ الذي يدفعه العميل؟
تعرض الصفحة المستضافة المبلغ الدقيق للأصل المختار بسعر صرف ثابت طوال مدة صلاحية الفاتورة.
