الانتقال إلى المحتوى الرئيسي

​
نظرة عامة

يرجع Dodo Payments سبب فشل مفصل كلما لم تنجح محاولة الدفع. يتم توحيد هذه الأسباب عبر طرق الدفع والمزودين، بحيث يمكنك تنفيذ معالجة متسقة في تطبيقك. عند فشل الدفع، يُظهر payment.failed webhook وكائن الدفع:
  • error_code — سبب فشل موحد من الجدول أدناه.
  • error_message — تفسير يمكن للبشر قراءته.
  • retry_attempt — 0 للشحنة الأصلية، 1 أو أعلى لكل محاولة تجديد اشتراك مجدولة.
فهم هذه الأسباب للفشل يتيح لك تقديم ملاحظات واضحة للعملاء، وتقرير ما إذا كانت محاولة الاسترداد تستحق، واسترداد المزيد من الإيرادات.

Handle Payment Failures

دليل خطوة بخطوة للمطور لقراءة هذه الرموز من webhooks وAPI، وتوضيحها للعملاء، وتحديد متى يجب إعادة المحاولة.

​
الرفض المؤقت مقابل الرفض الدائم

كل شفرة فشل تندرج في واحدة من فئتين. يحدد هذا الفرق ما إذا كان يجب عليك إعادة المحاولة لنفس طريقة الدفع أو طلب طريقة جديدة من العميل. بالنسبة لتجديد الاشتراكات، يطبق Dodo Payments هذا التمييز تلقائيًا: يتم إعادة محاولة الرفض المؤقت بواسطة إعادة محاولة دفع الاشتراك، بينما يؤدي الرفض الدائم إلى إنهاء سلسلة المحاولات فورًا ويفضل التعامل معها باستخدام إدارة اشتراك الرفض.
لا تكشف عن السبب الحقيقي لـ STOLEN_CARD, LOST_CARD, PICKUP_CARD, أو FRAUDULENT للعميل. يمكن أن يؤدي توضيح هذه إلى تنبيه ممثل احتيالي. أظهر دائمًا رسالة رفض عامة للعميل (على سبيل المثال، “لقد تم رفض بطاقتك. يرجى الاتصال بمصرفك أو استخدام بطاقة أخرى.”) وسجل فقط الشفرة المحددة داخليًا.

​
أسباب فشل المعاملة

يسرد الجدول التالي كل شفرة فشل، نوع الرفض، ما إذا كان يمكن للعميل حلها، الوصف، والإجراء الموصى به.
خطأ المستخدم يشير إلى ما إذا كان يمكن للعميل حل رفض الدفع أم لا. عندما Yes، يمكن للعميل اتخاذ إجراء لإصلاح المشكلة (على سبيل المثال، إدخال تفاصيل البطاقة الصحيحة). عندما No، يعود الرفض إلى مشاكل على مستوى النظام أو قيود مصرفية لا يمكن للعميل حلها مباشرة.
يمكن أيضًا رفض البطاقة عندما يقوم محرك المخاطر الخاص بالبنك المصدر بتحديد حامل البطاقة كعميل عالي المخاطر — بشكل مستقل عن التاجر أو تفاصيل المعاملة. تظهر هذه الرفضات عادةً كرموز عامة مثل DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED، أو FRAUDULENT. في هذه الحالات، لا يشارك البنك السبب المحدد، ولا يمكن لـ Dodo Payments ولا التاجر تجاوز القرار. اطلب من العميل الاتصال بالبنك لحل المشكلة، أو استخدام بطاقة أو طريقة دفع مختلفة.

​
التعامل مع الفشل برمجيًا

اقرأ error_code من payment.failed webhook أو كائن الدفع، وقم بتوجيهه للإجراء الموصى به أعلاه، وقرر ما إذا كان ستعيد المحاولة. بالنسبة لتجديدات الاشتراك، تتم إعادة المحاولة تلقائيًا في حالة الرفض الطفيف — انظر إعادة محاولات دفع الاشتراك. بالنسبة لأخطاء مستوى API والمنطق التجاري (مثل PAYMENT_NOT_SUCCEEDED أو REFUND_WINDOW_EXPIRED) التي لا تتعلق برفض البطاقات، راجع مرجع أكواد الأخطاء.

​
ذات صلة

Handle Payment Failures

دليل من البداية إلى النهاية لكشف، وإظهار، وإعادة محاولة المدفوعات الفاشلة.

Error Codes

أكواد خطأ API ومنطق الأعمال للفشل غير المرتبط بالرفض.

Subscription Payment Retries

إعادة المحاولات التلقائية التي تستعيد حالات الرفض الطفيف في تجديدات الاشتراك.

Subscription Dunning

تسلسل البريد الإلكتروني الذي يستعيد حالات الرفض الحاد عن طريق مطالبة بتحديث طريقة الدفع.

​
الدعم

للحصول على مساعدة إضافية بشأن فشل المعاملات أو مشكلات التكامل، يرجى الاتصال بفريق الدعم لدينا على support@dodopayments.com.
آخر تعديل في ٢٦ يونيو ٢٠٢٦