أكواد الرفض

الصفحة دي هي وجهة كل lastPaymentError.docUrl اللي كوده جه من DeclineCode. الإرساء (anchors) هنا بيطابق قيمة declineCode، فـ https://docs.xpay.app/integrate/errors/decline-codes#insufficient_funds بيوصلك مباشرةً للصف اللي تحت.

كود الرفض هو سبب البنك المُصدِر لرفض العملية، متطبّع في مفردات XPay. بيتظبّط على رفض البطاقات بس؛ ولحالات فشل الدفع غير البطاقية، lastPaymentError.declineCode بيبقى null وبتقرا code بدلًا منه. شوف أكواد أخطاء الدفع.

قراءة networkDeclineCode

جنب declineCode، كل رفض بطاقة بيحمل networkDeclineCode: كود من 2-4 أرقام بترجعه شبكة البطاقة (الكود الحرفي من رسالة ISO 8583، أو نصيحة ICCNetwork، أو ما يعادلها حسب ماركة البطاقة).

حاجتين تعرفهم:

• المعنى خاص بالماركة. الـ 51 من Visa معناه "عدم كفاية الرصيد" لكن نفس الكود على شبكة تانية ممكن يتعيّن لحاجة مختلفة تمامًا. خُد ماركة البطاقة في الاعتبار وإنت بتفسّر الكود الخام.
• هو تمرير، مش تطبيع. XPay ما بيترجمش 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_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

البنك المُصدِر بيطلب من التاجر إنه يعيد إرسال العملية.

وضع الاختبار

testmode_decline

الرفض ده بيتطلق في وضع الاختبار بس. استخدم مصفوفة بطاقات الاختبار في وضع الاختبار وبطاقات الاختبار علشان تحرّك نتائج رفض معيّنة أثناء التطوير.

رايح فين بعد كده