نظرة عامة
يرجع Dodo Payments سبب فشل مفصل كلما لم تنجح محاولة الدفع. يتم توحيد هذه الأسباب عبر طرق الدفع والمزودين، بحيث يمكنك تنفيذ معالجة متسقة في تطبيقك. عند فشل الدفع، يُظهرpayment.failed webhook وكائن الدفع:
error_code— سبب فشل موحّد من الجدول أدناه.error_message— شرح مقروء للبشر مكتوب لك، بصفتك التاجر. عندما يكونerror_codeأحد الرموز الموحّدة أدناه، يكون هذا عنوانًا رئيسيًا مع الإجراء الموصى به بدلًا من النص الخام من معالج الدفع.retry_attempt—0للرسوم الأصلية، و1أو أعلى لكل إعادة محاولة مجدولة لتجديد الاشتراك.
نص التاجر مقابل نص العميل
يرتبط كل رمز فشل موحّد برسالتين مختلفتين، حتى يرى الجمهور المناسب مستوى التفاصيل المناسب:يعرض 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 أو من كائن الدفع، ثم اربطه بالإجراء الموصى به أعلاه وحدد ما إذا كانت هناك حاجة إلى إعادة المحاولة. بالنسبة إلى تجديدات الاشتراكات، تتم إعادة محاولة حالات الرفض المؤقتة تلقائيًا نيابةً عنك — راجع Subscription Payment Retries.
بالنسبة إلى أخطاء مستوى API وأخطاء منطق الأعمال (مثل PAYMENT_NOT_SUCCEEDED أو REFUND_WINDOW_EXPIRED) التي لا تمثل حالات رفض للبطاقات، راجع مرجع Error Codes.
ذات صلة
Handle Payment Failures
دليل شامل لاكتشاف المدفوعات الفاشلة وعرضها وإعادة محاولتها.
Error Codes
رموز أخطاء API وأخطاء منطق الأعمال للفشل الذي لا يتعلق بالرفض.
Subscription Payment Retries
إعادات المحاولة التلقائية التي تستعيد حالات الرفض المؤقتة أثناء تجديدات الاشتراكات.
Subscription Dunning
تسلسلات بريد إلكتروني تستعيد حالات الرفض الدائمة من خلال طلب تحديث طريقة الدفع.