4 نقاط نهاية

الدفع المباشر

الاستدعاءات التي تنفّذها صفحة الدفع نفسها: التحقق من الجلسة، وإرسال بيانات البطاقة، وعودة ‎3-D Secure.

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

بكلمات بسيطة

نموذج البطاقة الخاص بكم، مُدارًا خطوة خطوة.

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

فقط إن كنتم تبنون نموذج البطاقة بأنفسكم. هذه النقاط لا يصادق عليها مفتاحكم بل الجلسة، وهي تُدخلكم في نطاق الامتثال لبيانات البطاقات.

كيف تدمجونها

1استخرجوا معرّف الجلسة ومفتاح التحقق (vk) ذا الاستعمال الواحد — يعودان في استجابة إنشاء الجلسة، أو تحملهما إعادة توجيه payUrl — ثم تحققوا من الجلسة بهذا الزوج للحصول على سياق العرض: تُستهلك vk بهذا التحقق.
2أرسلوا بيانات البطاقة بذلك المفتاح — لا بمفتاح الواجهة.
3اتبعوا إعادة توجيه ‎3-D Secure إن طلبها البنك، ثم أكّدوا العودة.
4استعلموا عن حالة الدفع للعرض، وانتظروا الويب هوك للقرار التجاري.

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

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

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

POST/checkout/verifyالتحقق من جلسة دفع
POST/checkout/submitإرسال بيانات البطاقة لجلسة دفع
POST/checkout/returnتأكيد العودة من ‎3-D Secure
GET/checkout/payments/{reference}الحصول على حالة الدفع الموجّهة إلى المشتري

POST200

التحقق من جلسة دفع

يفتح جلسة دفع للأداء باستخدام sessionId الخاص بها ومفتاح التحقق (vk) الوارد في استجابة إنشاء الجلسة. يُرجع مبلغ الجلسة وعملتها وهويتها البصرية وقدراتها. يجب استدعاء verify قبل submit؛ وفي الجلسة أحادية الاستخدام يُستهلك vk عند أول verify ولا يمكن إعادة استخدامه. بدون مفتاح API — لا ترسلوا X-CHARI-PAY-API-KEY.

المخطط · CheckoutVerifyRequest

الحقل	النوع	الموضع	مطلوب	الوصف
`sessionId`	string	body	مطلوب	معرّف الجلسة الوارد في استجابة إنشاء الجلسة.
`vk`	string	body	مطلوب	مفتاح التحقق (verifyKey) من استجابة إنشاء الجلسة؛ يُستخدم مرة واحدة في الجلسات ذات الاستخدام الواحد.

POST200

إرسال بيانات البطاقة لجلسة دفع

يؤدّي جلسة تم التحقق منها بواسطة بطاقة، من خادم إلى خادم (بدون صفحة مستضافة). الشروط المسبقة: يجب استدعاء verify أولاً؛ وإذا أُنشئت الجلسة بـ keepAlive=true فإن savePaymentMethodConsent=true إلزامي؛ كما أن الترويسة Idempotency-Key إلزامية للجلسة القابلة لإعادة الاستخدام (غير أحادية الاستخدام). يُرجع حالة نهائية، أو PENDING_3DS مع redirectionUrl يجب على المشتري فتحه لإتمام تحدي ‎3-D Secure — ثم استدعوا POST /checkout/return. يتحمل المستدعون الذين يعالجون بيانات البطاقة الخام مسؤولية امتثالهم لمعيار PCI DSS. بدون مفتاح API — لا ترسلوا X-CHARI-PAY-API-KEY.

المخطط · CheckoutSubmitRequest

الحقل	النوع	الموضع	مطلوب	الوصف
`Idempotency-Key`	string	header	اختياري	إلزامي للجلسة القابلة لإعادة الاستخدام؛ واختياري (ومُوصى به) للجلسة ذات الاستخدام الواحد. تؤدي إعادة إرسال المفتاح نفسه إلى إعادة النتيجة الأولى.
`sessionId`	string	body	مطلوب	معرّف جلسة تم التحقق منها مسبقًا.
`card`	Card	body	مطلوب
`card.firstName`	string	body	مطلوب
`card.lastName`	string	body	مطلوب
`card.pan`	string	body	مطلوب	رقم البطاقة الكامل (PAN). لا يُخزَّن أبدًا دون إخفاء.
`card.expiryDate`	string	body	مطلوب	تاريخ انتهاء صلاحية البطاقة، بصيغة MM/YY.
`card.cvv`	string	body	مطلوب
`card.cardName`	string	body	اختياري	الاسم كما هو مطبوع على البطاقة.
`savePaymentMethodConsent`	boolean	body	اختياري	موافقة صريحة من المشتري على حفظ وسيلة الدفع؛ مطلوبة (true) عندما تكون الجلسة بقيمة keepAlive=true، ويتم تجاهلها في غير ذلك.

POST200

تأكيد العودة من ‎3-D Secure

يربط عودة المشتري من تحدّي ‎3-D Secure بالعملية المرسلة، ويُعيد الحالة النهائية إضافة إلى redirectUrl الخاص بالتاجر للقبول أو الرفض. استدعوه بعد أن يُكمل المشتري redirectionUrl المُعاد من submit. لا يتطلب مفتاح API.

المخطط · CheckoutReturnRequest

الحقل	النوع	الموضع	مطلوب	الوصف
`sessionId`	string	body	مطلوب
`operationId`	integer (int64)	body	مطلوب

GET200

الحصول على حالة الدفع الموجّهة إلى المشتري

يحدّد حالة الدفع انطلاقًا من مرجع الطلب، أو مرجع رابط الدفع، أو معرّف بوابة المزوّد الوارد من عودة ‎3-D Secure. يُجيب دائمًا بمرجعنا ولا يحمل أي بيانات شخصية. استخدموه للاستعلام عن النتيجة بعد submit/return. بدون مفتاح API.

الحقل	النوع	الموضع	مطلوب	الوصف
`reference`	string	path	مطلوب	مرجع الطلب، أو مرجع رابط الدفع، أو معرّف بوابة المزوّد.

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

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

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

اتصلوا بنا