نظرة عامة
عند فشل محاولة دفع، تُرجع Dodo Payments رمز فشل موحّدًا يوضح السبب. تكون الرموز نفسها عبر طرق الدفع ومعالجات الدفع، لذا تغطي مجموعة واحدة من قواعد المعالجة كل دفعة فاشلة. يعرض webhook payment.failed وكائن الدفع هذه الحقول للدفعة الفاشلة:
error_code: رمز فشل موحّد من الجدول أدناه.error_message: شرح مكتوب لك، بصفتك التاجر. عندما يكونerror_codeأحد الرموز الموحّدة أدناه، يكون هذا الشرح عنوانًا مع الإجراء المقترح، وليس النص الخام من معالج الدفع.retry_attempt: 0للرسوم الأصلية، و1أو أعلى لكل إعادة محاولة مجدولة لتجديد الاشتراك. تحتفظ الدفعات التي لا تمثل تجديدات اشتراك بالقيمة0.
نص التاجر مقابل نص العميل
يرتبط كل رمز فشل موحّد برسالتين، واحدة لك وأخرى لعميلك:يعرض Customer Portal صياغة العميل في
error_message، بينما تعرض merchant API صياغة التاجر للدفع نفسه. ويكون error_code متطابقًا في الحالتين.Handle Payment Failures
دليل مطوّر خطوة بخطوة لقراءة هذه الرموز من webhooks وAPI، وعرضها للعملاء، وتحديد متى تجب إعادة المحاولة.
حالات الرفض المؤقت والدائم
يكون كل رمز فشل إما رفضًا مؤقتًا أو رفضًا نهائيًا. يوضح النوع ما إذا كانت محاولة لاحقة باستخدام تفاصيل الدفع نفسها قد تنجح، أو ما إذا كان يجب على العميل اتخاذ إجراء أولًا.
بالنسبة إلى تجديدات الاشتراكات، تطبق Dodo Payments هذا التصنيف تلقائيًا. تعيد Subscription Payment Retries محاولة الدفعات المرفوضة مؤقتًا. ينهي الرفض النهائي سلسلة إعادة المحاولة فورًا؛ ويمكن استرداده باستخدام Subscription Dunning.
أسباب فشل المعاملات
يسرد الجدول التالي كل رمز فشل، مع نوع الرفض، وما إذا كان بإمكان العميل حله، والوصف، والإجراء المقترح.يوضح خطأ المستخدم ما إذا كان بإمكان العميل حل الرفض. يعني
Yes أن بإمكان العميل إصلاح المشكلة، مثل إدخال تفاصيل البطاقة الصحيحة. أما No فيعني أن الرفض ناتج عن مشكلة على مستوى النظام أو تقييد من المصرف، ولا يستطيع العميل حله مباشرة.يمكن للبنك المُصدِر أيضًا رفض البطاقة لأن محرّك المخاطر الخاص به يصنّف حامل البطاقة على أنه عالي المخاطر، بصرف النظر عن التاجر أو تفاصيل المعاملة. تظهر عمليات الرفض هذه عادةً على شكل رموز عامة مثل
DO_NOT_HONOR أو GENERIC_DECLINE أو CARD_DECLINED أو TRANSACTION_NOT_APPROVED أو FRAUDULENT. لا يشارك البنك السبب المحدد، ولا يمكن لـ Dodo Payments أو التاجر تجاوز هذا القرار. اطلب من العميل التواصل مع بنكه لحل سبب وضع علامة المخاطر، أو استخدام بطاقة أو طريقة دفع مختلفة.معالجة حالات الفشل برمجيًا
اقرأerror_code من webhook payment.failed أو من كائن الدفع، واربطه بالإجراء المقترح في الجدول، ثم قرر ما إذا كنت ستعيد المحاولة. بالنسبة إلى تجديدات الاشتراك، تعيد Dodo Payments محاولة الدفعات المرفوضة مؤقتًا نيابةً عنك. راجع Subscription Payment Retries.
بالنسبة إلى أخطاء API وأخطاء منطق الأعمال التي لا تمثل رفضًا للبطاقة، مثل PAYMENT_NOT_SUCCEEDED أو REFUND_WINDOW_EXPIRED، راجع مرجع Error Codes.
ذات صلة
Handle Payment Failures
دليل شامل لاكتشاف المدفوعات الفاشلة وعرضها وإعادة محاولتها.
Error Codes
رموز أخطاء API وأخطاء منطق الأعمال للفشل الذي لا يتعلق بالرفض.
Subscription Payment Retries
إعادات المحاولة التلقائية التي تستعيد حالات الرفض المؤقتة أثناء تجديدات الاشتراكات.
Subscription Dunning
تسلسلات بريد إلكتروني تستعيد حالات الرفض الدائمة من خلال طلب تحديث طريقة الدفع.