مقدمة
XPay بيوضّح حالات الفشل في مكانين مختلفين: جسم رد استدعاء API عملته، وحقل lastPaymentError على عملية دفع فشلت. اختار المكان اللي يناسب مشكلتك.
XPay بيوضّح حالات الفشل في مكانين مختلفين، والاتنين بيتعاملوا بنمطين مختلفين. اختار اللي يناسب اللي حصل دلوقتي:
- استدعاء API عمله السيرفر بتاعك رجّع رد غير 2xx. الخطأ في جسم رد الـ HTTP. بتتعامل معاه في المكان اللي الاستدعاء بيحصل فيه. ← أخطاء API.
- عملية دفع لعميل فشلت. الخطأ بيقعد على حقل
lastPaymentErrorبتاع الـ Payment Intent لباقي عمره. بتقراه بعد محاولة الدفع، في معالِج الـ webhook بتاعك أو في لوحة التحكم. ← أخطاء الدفع.
المكانين دول مش بيتشاركوا في قائمة أكواد ومش بيتشاركوا في مساحة عناوين URL للتوثيق. باقي مجموعة الأخطاء متقسّمة على الخط ده.
المكانين بنظرة سريعة
| أخطاء API | أخطاء الدفع | |
|---|---|---|
| إمتى بتقابله | بشكل متزامن، كرد على استدعاء API | بشكل غير متزامن، على الـ Payment Intent اللي فشل |
| فين بيعيش | جسم رد الـ HTTP: { error: { type, code, ... }, request_id } | حقل lastPaymentError بتاع الـ Payment Intent |
| إيه اللي سبّبه | طلبك اترفض (تحقّق، أو مصادقة، أو مورد ناقص، أو تعارض) | بطاقة العميل اترفضت، أو المعالج فشل |
| مين جمهور الرسالة | المهندسين بتوعك | عميلك (أحيانًا)، وفريق الدعم بتاعك (دايمًا) |
| مساحات الأكواد | واحدة: ApiErrorCode | ثلاثة: PaymentErrorCode، وDeclineCode، وكود الشبكة الخام |
| شكل المعالِج | try / catch، وتفرّع على error.type وerror.code | اقرا lastPaymentError، وتفرّع على adviceCode، واختار نص آمن للعميل |
| المرجع | أكواد أخطاء API | أكواد أخطاء الدفع، أكواد الرفض |
حاجتين كل خطأ بيديهملك
request_id
كل رد API (سواء 2xx أو خطأ) بيتضمن request_id زي req_3STkwmFGhGHoO0IX13BRo5iU. في ردود الأخطاء بيبقى على المستوى الأعلى جنب error. اذكره في تذاكر الدعم، وسجّله جنب كل خطأ بيمسكه المعالِج بتاعك، واستخدمه علشان تلاقي الاستدعاء الفاشل في Workbench ← السجلات حيث تقدر تشوف الطلب والرد كاملين.
عملية الدفع الفاشلة كمان ليها request_id على استدعاء الـ API الأساسي اللي طلّقها (الـ POST /checkout/sessions/.../pay من متصفح العميل). lastPaymentError.chargeId زائد وقت الفشل عادةً كفاية علشان تلاقي السجل ده لو احتجته.
docUrl
كل كود خطأ ليه رابط مباشر لصفه على صفحة مرجع الأكواد في موقع التوثيق ده:
- أكواد أخطاء API ←
https://docs.xpay.app/integrate/errors/api-error-codes#<code> - أكواد أخطاء الدفع ←
https://docs.xpay.app/integrate/errors/payment-error-codes#<code> - أكواد الرفض ←
https://docs.xpay.app/integrate/errors/decline-codes#<code>
لوحة التحكم بتعرض الرابط ده في تلميحات المعاملات وفي Workbench ← السجلات علشان تقدر تضغط على طول من حدث فاشل لشرحه. في الواجهة التشغيلية بتاعتك إنت، اعرض الـ docUrl كرابط "اعرف أكتر" جنب رسالة الخطأ.
اختار رايح فين بعد كده
أخطاء API
مغلّف الخطأ، وأنواع الأخطاء الثلاثة، ونمط المعالجة (try/catch + تفرّع على type).
أكواد أخطاء API
القائمة الكاملة لقيم error.code اللي ممكن تستقبلها على استدعاء API فاشل، متجمّعة حسب المجال.
أخطاء الدفع
شكل lastPaymentError، والـ adviceCode اللي بيقرّر اللي تعمله بعد كده، وإزاي تقسّم النص بين
عميلك وفريقك.
أكواد أخطاء الدفع
كل قيمة لـ lastPaymentError.code، مع النص الآمن للعميل والنص الموجّه للتاجر اللي XPay بيرجّعه.
أكواد الرفض
سبب البنك المُصدِر للرفض، في lastPaymentError.declineCode. بالإضافة لكود الشبكة الخام اللي رجع
من ماركة البطاقة.
لوحة السجلات
دوّر على أي حالة فشل بـ request_id بتاعها وشوف الطلب والرد كاملين.