أكواد الرفض
سبب رفض العملية اللي بيرجع في `lastPaymentError.declineCode`: أكواد رفض البطاقات وأكواد رفض مزوّد الدفع. بالإضافة لإزاي تقرا تمرير `networkDeclineCode` الخام.
الصفحة دي هي وجهة كل lastPaymentError.docUrl اللي كوده جه من DeclineCode. الإرساء (anchors) هنا بيطابق قيمة declineCode، فـ https://docs.xpay.app/integrate/errors/decline-codes#insufficient_funds بيوصلك مباشرةً للصف اللي تحت.
كود الرفض هو سبب رفض العملية، متطبّع في مفردات XPay. بيتظبّط على كل رفض، لكل طرق الدفع، في واحدة من عيلتين: أكواد رفض البطاقات لما البنك المُصدِر يرفض دفع بالبطاقة (lastPaymentError.code بيبقى card_declined)، وأكواد رفض مزوّد الدفع لما مزوّد أي طريقة دفع تانية، زي فاليو أو فوري، يرفضها (lastPaymentError.code بيبقى payment_declined). ولحالات الفشل اللي ما فيهاش رفض، زي أخطاء المعالج أو المحاولات المتروكة، lastPaymentError.declineCode بيبقى null وبتقرا code بدلًا منه. شوف أكواد أخطاء الدفع.
قراءة networkDeclineCode
جنب declineCode، كل رفض بطاقة بيحمل networkDeclineCode: كود من 2-4 أرقام بترجعه شبكة البطاقة (الكود الحرفي من رسالة ISO 8583، أو نصيحة ICCNetwork، أو ما يعادلها حسب ماركة البطاقة).
حاجتين تعرفهم:
- المعنى خاص بالماركة. الـ
51من Visa معناه "عدم كفاية الرصيد" لكن نفس الكود على شبكة تانية ممكن يتعيّن لحاجة مختلفة تمامًا. خُد ماركة البطاقة في الاعتبار وإنت بتفسّر الكود الخام. - هو تمرير، مش تطبيع. XPay ما بيترجمش
networkDeclineCodeلرسالة ودودة للعميل. استخدمه لتصعيد الدعم أو تحليل ما بعد الواقعة، مش للتفرّع وقت التشغيل.
في رفض مزوّد الدفع، networkDeclineCode بيبقى كود الاستجابة الخاص بالمزوّد، ومعناه بيحدده المزوّد؛ اتعامل معاه بنفس الطريقة.
للتفرّع وقت التشغيل، استخدم declineCode (مفردات XPay المطبّعة، المسرودة تحت) وadviceCode (رمز الإجراء الموصوف في أخطاء الدفع). اعتبر networkDeclineCode أثر لتذاكر الدعم.
الرفض الشائع
أكتر الأسباب اللي البنوك المُصدِرة بترجعها.
generic_decline
البنك المُصدِر رفض من غير سبب محدّد. غالبًا بديل لما نموذج المخاطر بتاع البنك المُصدِر يرفض لكن ما يقولناش ليه.
insufficient_funds
الرصيد المتاح للعميل مش قادر يغطّي العملية.
lost_card
البطاقة اتبلّغ عنها ضايعة. ما تعيدش المحاولة؛ البنك المُصدِر علّم على البطاقة.
stolen_card
البطاقة اتبلّغ عنها مسروقة. ما تعيدش المحاولة.
expired_card
البطاقة منتهية. العميل محتاج يستخدم بطاقة تانية.
incorrect_cvc
الـ CVC/CVV اللي العميل دخّله ما بيطابقش اللي عند البنك المُصدِر.
incorrect_number
رقم البطاقة عدّى فحوصات الصيغة لكن البنك المُصدِر بيقول إنه غلط.
incorrect_zip
الرمز البريدي في عنوان فوترة العميل ما بيطابقش اللي عند البنك المُصدِر.
incorrect_address
عنوان الشارع ما طابقش. فحص الـ AVS فشل.
المصادقة
نتائج 3D Secure والمصادقة المتدرّجة.
authentication_required
البنك المُصدِر بيتطلّب مصادقة 3D Secure. العميل محتاج يكمّل التحدّي.
authentication_failed
العميل ما عدّاش الـ 3D Secure: OTP غلط أو منتهي، أو لغى التحدّي، أو البنك المُصدِر رفضه. مفيش حاجة اتخصمت. العميل يقدر يحاول تاني أو يستخدم بطاقة تانية.
authentication_not_handled
العميل تخطّى أو ما كمّلش خطوة مصادقة مطلوبة.
mobile_device_authentication_required
البطاقة بتتطلّب إن العميل يعيد المصادقة على جهاز موبايل (مثلًا بصمة بيومترية للدفع باللمس).
المعالجة
البنك المُصدِر قبل الطلب لكن رفض وقت المعالجة.
processing_error
خطأ معالجة عام من ناحية البنك المُصدِر. عادةً عابر.
do_not_honor
البنك المُصدِر رجّع "do not honor" من غير تفصيل أكتر. عادةً معناه إن العميل المفروض يتواصل مع بنكه.
call_issuer
البنك المُصدِر قال للعميل يتواصل معاه مباشرةً. اعرض للعميل رسالة واضحة "كلّم بنكك".
card_not_supported
البطاقة ما بتدعمش نوع الشراء ده (مثلًا، بعض بطاقات الخصم بترفض فئات تجارية معيّنة).
currency_not_supported
حساب البطاقة ما بيدعمش عملة العملية.
duplicate_transaction
البنك المُصدِر اكتشف عملية شبه متطابقة مؤخرًا ورفض كتكرار.
approve_with_id
رد محدّد من البنك المُصدِر معناه عمليًا "كنا هنوافق بهوية إضافية". عادةً آمن تعرض رسالة "حاول تاني".
الحدود
البطاقة أو الحساب وصل لحد.
card_velocity_exceeded
البطاقة اتستخدمت مرات كتير في فترة قصيرة. البنك المُصدِر بيحدّد المعدّل.
withdrawal_count_limit_exceeded
البطاقة وصلت حد عدد عمليات السحب/المعاملات لكل فترة بتاعها.
الاحتيال والمخاطر
البنك المُصدِر أو الشبكة علّم على العملية للمخاطر.
fraudulent
اشتباه احتيال. ما تعيدش المحاولة.
merchant_blacklist
البطاقة محظورة تحديدًا لحسابك التجاري.
pickup_card
البنك المُصدِر بيطلب إن البطاقة تتاخد فعليًا. ما تعيدش المحاولة.
restricted_card
البطاقة عليها قيود بتمنع العملية دي.
security_violation
فحص أمان فشل على مستوى البنك المُصدِر أو الشبكة.
مشاكل الحساب
حساب البطاقة نفسه فيه مشكلة مش مرتبطة بالعملية دي تحديدًا.
invalid_account
حساب البطاقة غير صالح بالنسبة للبنك المُصدِر.
new_account_information_available
البطاقة اتعمل ليها إصدار جديد. البنك المُصدِر بيشير إن العميل عنده بيانات بطاقة جديدة.
transaction_not_allowed
البنك المُصدِر ما بيسمحش بنوع العملية ده على البطاقة دي.
service_not_allowed
التاجر أو الخدمة مش مسموح بيهم للبطاقة دي.
not_permitted
رد عام "غير مسموح" من البنك المُصدِر.
الرقم السري (PIN)
أخطاء الرقم السري غالبًا بتظهر للمعاملات الحضورية أو اللي فيها رقم سري محفوظ؛ نادرة في مسارات التجارة الإلكترونية العادية لكن مسرودة للاكتمال.
incorrect_pin
الرقم السري المدخل ما طابقش.
invalid_pin
صيغة الرقم السري غير صالحة.
pin_try_exceeded
حامل البطاقة تعدّى الحد الأقصى لمحاولات الرقم السري.
offline_pin_required
البطاقة بتتطلّب إدخال رقم سري دون اتصال، اللي مش متاح في المسار ده.
online_or_offline_pin_required
البطاقة بتتطلّب إدخال رقم سري (باتصال أو دون اتصال) وما اتدخلش.
المبلغ
invalid_amount
مبلغ العملية نفسه اترفض من البنك المُصدِر (غالبًا بيقع خارج حدود لكل معاملة المظبوطة على البطاقة).
الإلغاء
إيقافات بادر بيها العميل على عمليات الخصم التلقائية.
revocation_of_authorization
حامل البطاقة ألغى التفويض لعملية الخصم المتكرّرة دي تحديدًا.
revocation_of_all_authorizations
حامل البطاقة ألغى التفويض لكل عمليات الخصم المتكرّرة من التاجر ده.
stop_payment_order
العميل أصدر أمر إيقاف دفع.
no_action_taken
البنك المُصدِر ما عالجش العملية خالص. عادةً حالة عابرة؛ آمن إعادة المحاولة.
reenter_transaction
البنك المُصدِر بيطلب من التاجر إنه يعيد إرسال العملية.
أكواد رفض مزوّد الدفع
المدفوعات بطريقة دفع غير البطاقة، زي فاليو أو فوري، بتترفض بالأكواد دي، وlastPaymentError.code بيبقى payment_declined. كل كود هو سبب مزوّد الدفع للرفض. الأكواد اللي موجودة كمان في قائمة البطاقات معناها هو اللي تحت لما code يكون payment_declined.
declineCode | المعنى |
|---|---|
partner_generic_decline | مزوّد الدفع رفض العملية من غير ما يذكر سبب. |
invalid_customer_account | مزوّد الدفع مش قادر يخصم من حساب العميل (مثلًا مش متسجل، أو مش نشط، أو مش مؤهل). لو كل المدفوعات بالطريقة دي بتفشل بنفس الشكل، كلّم دعم XPay. |
payment_limit_exceeded | العملية أكبر من حد على حساب العميل عند المزوّد، زي الحد الائتماني المتاح. |
partner_high_risk_customer | مزوّد الدفع صنّف العميل إنه عالي المخاطر. ما تعيدش المحاولة، وما تقولش للعميل السبب. |
invalid_payment_information | المزوّد رفض بيانات الدفع اللي العميل استخدمها، زي رقم بطاقة أو رقم سري اتكتب في تطبيق المزوّد نفسه. |
lost_or_stolen_card | البطاقة اللي العميل استخدمها عند المزوّد متبلّغ عنها إنها ضايعة أو مسروقة. ما تعيدش المحاولة، وما تقولش للعميل السبب. |
authentication_failed | العميل ما كمّلش التحقق عند المزوّد، مثلًا رمز لمرة واحدة غلط أو منتهي. |
insufficient_funds | رصيد العميل عند مزوّد الدفع مش كفاية. |
processing_error | حصل خطأ في المعالجة عند مزوّد الدفع. ما اتخصمش أي مبلغ وإعادة المحاولة آمنة. |
currency_not_supported | مزوّد الدفع ما بيدعمش عملة العملية. |
invalid_amount | مزوّد الدفع ما بيسمحش بمبلغ العملية. |
expired_card | البطاقة اللي العميل استخدمها عند المزوّد منتهية. |
العميل اللي بيلغي من صفحة المزوّد، أو بيسيبها لحد ما تنتهي، ما اترفضش: المحاولة بتتسجل كمتروكة وlastPaymentError.code بيبقى payment_abandoned. ولما المزوّد يرفض الطلب نفسه أو يفشل من ناحيته، برضه مفيش رفض: declineCode بيبقى null وlastPaymentError.code بيبقى local_processor_rejected (إعادة المحاولة مش هتفيد، كلّم دعم XPay) أو processor_error (إعادة المحاولة آمنة).
وضع الاختبار
testmode_decline
الرفض ده بيتطلق في وضع الاختبار بس. استخدم مصفوفة بطاقات الاختبار في وضع الاختبار وبطاقات الاختبار علشان تحرّك نتائج رفض معيّنة أثناء التطوير.
رايح فين بعد كده
أكواد أخطاء الدفع
المرجع التاني لعمليات الدفع الفاشلة: قيم lastPaymentError.code.
أخطاء الدفع
النموذج: إزاي lastPaymentError متشكّل، بالإضافة لنمط المعالِج المحرَّك بـ adviceCode.
أكواد أخطاء API
مرجع الأخطاء اللي بترجع في ردود HTTP على استدعاءات الـ API بتاعتك.
أخطاء API
مغلّف الخطأ المتزامن.
مقدمة الأخطاء
رجوع للأول. خريطة المكانين.