الانتقال إلى المحتوى الرئيسي
حساب سندبوكساتصلوا بنا
توثيق الواجهة البرمجية

4 نقاط نهاية

جلسات الدفع

يتحوّل طلب المتجر الإلكتروني إلى جلسة: توجّهون المشتري إلى صفحة الدفع المستضافة وتستعيدون النتيجة.

عناوين النقاط وأوصافها تأتي من عقد OpenAPI، بالإنجليزية — فلا يمكن أن تحيد عن الواجهة.

بكلمات بسيطة

الأداء داخل موقعكم: طلبية واحدة، جلسة واحدة.

متى تستعملونها

لمتجر أو تطبيق يقع فيه الدفع داخل مسار طلب، بعناوين عودة وإلغاء تخصّكم. وتنتهي صلاحية الجلسة افتراضيًا بعد 72 ساعة من إنشائها — `expiresAt` لتقصيرها.

كيف تدمجونها

  1. 1أنشئوا الجلسة بالمبلغ ومرجع طلبكم — عناوين العودة اختيارية: بدونها تسري القيم الافتراضية لحسابكم.
  2. 2وجّهوا المشتري إلى عنوان الدفع الذي تستلمونه.
  3. 3عند عودته، اعرضوا حالة انتظار — فالعودة تقول إن المشتري رجع، لا إن الدفع تمّ.
  4. 4أكّدوا الطلب عند وصول الويب هوك، لا بالاعتماد على إعادة التوجيه وحدها.

بطاقة اختبار السندبوكس

تعمل السندبوكس على مسارات حقيقية مقابل بيئة اختبار: المسارات حقيقية، أما المال فلا. وبطاقة واحدة فقط مقبولة فيها.

هذا الـ PAN هو الوحيد المقبول. أي رقم آخر — بما فيه 4242… الخاص بمنصات أخرى — يُرفض عند المنبع — عادةً بخطأ 502 — مع الرمز الثابت BAAS_CHARI_ERROR. إن واجهتم هذا الخطأ أثناء الاختبار، فتحققوا أولًا من البطاقة المُدخلة.

POST

إلغاء جلسة دفع

يُنهي صلاحية الجلسة بحيث لا يمكن دفعها بعد ذلك. يُعيد حالة الجلسة المحدّثة.

الحقلالنوعالموضعمطلوبالوصف
sessionIdstringpathمطلوب
GET

عرض جلسات الدفع

تُرجع جلسات الدفع الخاصة بالجهة المستدعية لبيئة المفتاح، الأحدث أولًا. يمكنكم اختياريًا التصفية حسب مصدر الإنشاء باستخدام ?origin=API أو ?origin=DASHBOARD.

الحقلالنوعالموضعمطلوبالوصف
originenumqueryاختياريالتصفية حسب مصدر الإنشاء (API أو DASHBOARD).القيم APIDASHBOARD
pageablePageablequeryمطلوب
POST200

إنشاء جلسة دفع

تنشئ جلسة دفع للاستخدام مرة واحدة لطلبية معيّنة وتُرجع رابط checkoutUrl المستضاف الخاص بها. أرسلوا externalId اختياريًا من إنشائكم (فريدًا لكل تاجر) لجعل عملية الإنشاء idempotent (دون تكرار): يؤدي externalId المكرّر إلى إرجاع الجلسة الموجودة مع 200 OK. مرّروا ترويسة Idempotency-Key اختيارية لجعل إعادة المحاولات آمنة.

المخطط · CreateCheckoutSessionRequest

الحقلالنوعالموضعمطلوبالوصف
Idempotency-Keystringheaderاختياريمفتاح Idempotency اختياري؛ إعادة إرسال القيمة نفسها تُعيد النتيجة الأولى.
amountnumberbodyمطلوبالمبلغ المراد تحصيله، بالدرهم (الوحدة الرئيسية).
orderIdstringbodyمطلوبمرجع الطلب أو المرجع التجاري الخاص بكم لجلسة الدفع هذه.
singleUsebooleanbodyاختياريجلسة للاستخدام مرة واحدة (موصى به). القيمة الافتراضية true.
externalIdstringbodyاختياريمعرّف اختياري تقدّمونه أنتم، فريد لكل تاجر؛ تؤدي القيمة المكرّرة إلى إعادة إرجاع الجلسة الموجودة. يختلف عن orderId/externalReference اللذين لا يُفرض عليهما التفرّد.
configCheckoutSessionConfigbodyمطلوبالمشتري وروابط إعادة التوجيه وخيارات جلسة الدفع.
config.customerCheckoutSessionCustomerbodyمطلوبالمشتري الذي يُخصم منه المبلغ.
config.urlsCheckoutSessionUrlsbodyاختياريعناوين URL اختيارية لإعادة التوجيه / الإشعار. أي حقل غير مضبوط يعود إلى القيمة الافتراضية المهيّأة لدى التاجر، ثم إلى القيمة الافتراضية للمنصة.
config.keepAlivebooleanbodyاختيارييُبقي الجلسة نشطة بعد محاولة فاشلة ليتمكّن المشتري من إعادة المحاولة. القيمة الافتراضية false.
config.frontendCheckoutSessionFrontendbodyاختياريتخصيص بصري اختياري لصفحة الدفع المستضافة.
config.settlementCheckoutSessionSettlementbodyاختياريتوزيع اختياري — محفظة التاجر الفرعي المراد إيداع المبلغ فيها.
metadataobjectbodyاختياريكائن بيانات وصفية حر الشكل (≤ 4 KB) يُعاد إرساله في ويب هوك الدفع.
expiresAtstring (date-time)bodyاختياريانتهاء صلاحية الجلسة (ISO-8601 UTC). يجب أن يكون في المستقبل؛ افتراضيًا بعد 72 ساعة من الإنشاء.
notifyOnFailurebooleanbodyاختياريإرسال ويب هوك payment.failed أيضاً عند فشل الدفع. القيمة الافتراضية false.
GET

استرجاع جلسة دفع

تجلب الحالة الحالية لجلسة ما ومبلغها وتاريخ انتهائها بواسطة معرّفها.

الحقلالنوعالموضعمطلوبالوصف
sessionIdstringpathمطلوبمعرّف الجلسة.

تحدّثوا إلى مختص دمج

سؤال حول الدمج؟

يجيب فريقنا التقني فرق الإدماج، من أول استدعاء في السندبوكس حتى الانتقال إلى الإنتاج.

اتصلوا بنا