نظرة عامة
يرجع Dodo Payments سبب فشل مفصل كلما لم تنجح محاولة الدفع. يتم توحيد هذه الأسباب عبر طرق الدفع والمزودين، بحيث يمكنك تنفيذ معالجة متسقة في تطبيقك. عند فشل الدفع، يُظهرpayment.failed webhook وكائن الدفع:
error_code— سبب فشل موحد من الجدول أدناه.error_message— تفسير يمكن للبشر قراءته.retry_attempt—0للشحنة الأصلية،1أو أعلى لكل محاولة تجديد اشتراك مجدولة.
Handle Payment Failures
دليل خطوة بخطوة للمطور لقراءة هذه الرموز من webhooks وAPI، وتوضيحها للعملاء، وتحديد متى يجب إعادة المحاولة.
الرفض المؤقت مقابل الرفض الدائم
كل شفرة فشل تندرج في واحدة من فئتين. يحدد هذا الفرق ما إذا كان يجب عليك إعادة المحاولة لنفس طريقة الدفع أو طلب طريقة جديدة من العميل.| نوع الرفض | ماذا يعني | ماذا تفعل | أمثلة |
|---|---|---|---|
| رفض مؤقت | مؤقت أو قابل للتصحيح — يمكن للبطاقة نفسها أن تنجح في محاولة لاحقة أو بمجرد أن يصحح العميل مدخلاته. | من الآمن المحاولة مرة أخرى (بعد تأخير أو بمجرد أن يصحح العميل تفاصيله). | INSUFFICIENT_FUNDS, GENERIC_DECLINE, CARD_VELOCITY_EXCEEDED, PROCESSING_ERROR, NETWORK_ERROR, NETWORK_TIMEOUT, TRY_AGAIN_LATER |
| رفض دائم | نهائي — إعادة المحاولة بنفس البطاقة لن يغير النتيجة. | لا تقم بإعادة محاولة نفس البطاقة. اطلب من العميل استخدام طريقة دفع مختلفة أو الاتصال بمصرفه. | STOLEN_CARD, LOST_CARD, PICKUP_CARD, DO_NOT_HONOR, FRAUDULENT, INVALID_ACCOUNT |
أسباب فشل المعاملة
يسرد الجدول التالي كل شفرة فشل، نوع الرفض، ما إذا كان يمكن للعميل حلها، الوصف، والإجراء الموصى به.| شفرة الفشل | النوع | خطأ المستخدم | الوصف | الإجراء الموصى به |
|---|---|---|---|---|
AUTHENTICATION_FAILURE | مؤقت | نعم | فشل التحقق أثناء المعاملة | اطلب من العميل إعادة المحاولة وإكمال التحقق 3DS، أو استخدام بطاقة أخرى |
AUTHENTICATION_REQUIRED | مؤقت | نعم | مطلوب تحقق إضافي لإكمال المعاملة | حث العميل على إتمام التحقق 3DS. بالنسبة لتجديد الاشتراكات، اطلب من العميل العودة والمصادقة |
AUTHENTICATION_TIMEOUT | مؤقت | نعم | انتهت مهلة عملية التحقق | اطلب من العميل إعادة المحاولة وإكمال التحقق فورًا |
CARD_DECLINED | مؤقت | لا | تم رفض البطاقة من قبل البنك المصدر دون سبب محدد (رفض عام) | اطلب من العميل إعادة المحاولة، الاتصال بمصرفه، أو استخدام بطاقة أخرى |
CARD_NOT_ACTIVATED | مؤقت | نعم | لم يقم حامل البطاقة بتفعيل البطاقة | اطلب من العميل تفعيل البطاقة مع مصرفه، ثم إعادة المحاولة |
CARD_VELOCITY_EXCEEDED | مؤقت | نعم | تم محاولة عدد كبير من المعاملات خلال فترة قصيرة | اطلب من العميل الانتظار وإعادة المحاولة لاحقًا، أو الاتصادرة في البنك حول الحدود |
CUSTOMER_CANCELLED | مؤقت | نعم | قام العميل بإلغاء المعاملة | دع العميل يبدأ الخروج عندما يكون جاهزًا |
DO_NOT_HONOR | دائم | لا | رفض البنك المصدرة المعاملة بشكل صريح (رمز ISO 8583 05 — لا تشرّف)؛ تعتبر الشبكات هذا نهائيًا | اطلب من العميل الاتصال بمصرفه؛ لا تقم بإعادة المحاولة نفس البطاقة |
EXPIRED_CARD | دائم | نعم | انتهت صلاحية البطاقة | اطلب من العميل استخدام بطاقة بتاريخ صلاحية صالح |
FRAUDULENT | دائم | نعم | تم الإبلاغ عن المعاملة كمحتملة احتيالية | أظهر للعميل رسالة رفض عامة — لا تكشف عن السبب. اطلب منه استخدام بطاقة أخرى |
GENERIC_DECLINE | مؤقت | لا | تم رفض المعاملة لسبب غير محدد | اطلب من العميل الاتصال بمصرفه أو تجربة بطاقة أخرى |
INCORRECT_CVC | مؤقت | نعم | كود CVC المقدم غير صحيح | اطلب من العميل إعادة إدخال الكود CVC الصحيح |
INCORRECT_NUMBER | مؤقت | نعم | تم إدخال رقم البطاقة بشكل غير صحيح | اطلب من العميل إعادة إدخال رقم البطاقة الصحيح |
INSUFFICIENT_FUNDS | مؤقت | نعم | ليس هناك أموال كافية في الحساب لإتمام المعاملة | اطلب من العميل استخدام طريقة دفع أخرى أو إعادة المحاولة عند توفر الأموال |
INVALID_ACCOUNT | دائم | نعم | تفاصيل الحساب المقدمة غير صالحة | اطلب من العميل الاتصال بمصرفه أو استخدام بطاقة أخرى |
INVALID_AMOUNT | مؤقت | نعم | مبلغ المعاملة غير صالح | تحقق من المبلغ وأي حدود شراء مع العميل |
INVALID_CARD_NUMBER | مؤقت | نعم | صيغة رقم البطاقة غير صالحة | اطلب من العميل إعادة إدخال رقم بطاقة صالح |
INVALID_CARD_OWNER | مؤقت | نعم | معلومات حامل البطاقة غير صالحة | اطلب من العميل تصحيح اسم حامل البطاقة |
INVALID_CVC | مؤقت | نعم | صيغة CVC غير صالحة | اطلب من العميل إعادة إدخال CVC صالح |
INVALID_EXPIRY_YEAR | مؤقت | نعم | سنة انتهاء صلاحية البطاقة غير صالحة | اطلب من العميل إدخال تاريخ انتهاء صلاحية صالح |
INVALID_PIN | مؤقت | نعم | الرقم السري المقدم غير صحيح | اطلب من العميل إعادة إدخال الرقم السري الصحيح |
INVALID_REQUEST | مؤقت | نعم | طلب المعاملة يحتوي على بيانات غير صالحة | تحقق من حقول طلب الدفع وأعد الإرسال ببيانات صالحة |
INVALID_UPI_ID | مؤقت | نعم | معرف UPI المقدم غير صالح | اطلب من العميل إدخال معرف UPI صالح |
LIMIT_EXCEEDED | مؤقت | نعم | تتجاوز المعاملة حد البطاقة أو الحساب | اطلب من العميل الاتصال بمصرفه حول الحدود، أو استخدام طريقة أخرى |
LIVE_MODE_TEST_CARD | دائم | نعم | تم استخدام بطاقة اختبار في وضع الحي | استخدم بطاقة حقيقية — ستفشل المحاولة باستخدام بطاقة الاختبار دائمًا في وضع الحي |
LOST_CARD | دائم | نعم | تم الإبلاغ عن البطاقة كضائعة | أظهر للعميل رسالة رفض عامة — لا تكشف عن السبب. اطلب منه استخدام بطاقة أخرى |
MANDATE_INVALID | مؤقت | نعم | أمر الدفع غير صالح | اطلب من العميل إعداد أمر الدفع مرة أخرى |
MANDATE_REQUIRED | مؤقت | نعم | مطلوب أمر لهذه المعاملة | أعد إعداد الأمر واطلب من العميل تفويضه قبل الخصم |
MANDATE_REQUIRED_SYSTEM | دائم | لا | النظام يتطلب أمرًا لهذا النوع من المعاملات | تأكد من إتمام تدفق إعداد الأمر قبل الخصم |
NETWORK_ERROR | مؤقت | لا | حدث خطأ في الشبكة أثناء المعاملة | مؤقت — أعد المحاولة بعد فترة قصيرة |
NETWORK_TIMEOUT | مؤقت | لا | انتهت مهلة طلب الشبكة | مؤقت — أعد المحاولة بعد فترة قصيرة |
ORDER_ALREADY_EXISTS | مؤقت | لا | طلب موجود بالفعل لهذه المعاملة (إنشاء طلب مكرر) | تحقق من حالة الطلب الحالي قبل إعادة المحاولة؛ اتصل بالدعم إذا استمر |
ORDER_CREATION_FAILED | مؤقت | لا | فشل في إنشاء الطلب للمعاملة | خطأ مؤقت/النظام — أعد المحاولة؛ اتصل بالدعم إذا استمر |
PAYMENT_METHOD_PROVIDER_DECLINED | دائم | نعم | رفض موفر طريقة الدفع المعاملة | اطلب من العميل الاتصال بموفره أو استخدام طريقة دفع أخرى |
PAYMENT_METHOD_UNSUPPORTED | دائم | نعم | الطريقة الدفع غير مدعومة لهذه المعاملة | اطلب من العميل استخدام طريقة دفع مدعومة |
PICKUP_CARD | دائم | نعم | تم الإبلاغ عن البطاقة كضائعة أو مسروقة وتم وضع علامة عليها للتسليم | أظهر للعميل رسالة رفض عامة — لا تكشف عن السبب. اطلب منه استخدام بطاقة أخرى |
PROCESSING_ERROR | مؤقت | لا | حدث خطأ أثناء معالجة المعاملة | مؤقت — أعد المحاولة؛ إذا استمر، اطلب من العميل الاتصال بمصرفه |
PROVIDER_UNSUPPORTED | دائم | لا | موفر الدفع لا يدعم نوع هذه المعاملة | اطلب من العميل استخدام طريقة دفع أخرى |
REENTER_TRANSACTION | مؤقت | نعم | تحتاج المعاملة إلى إعادة الإدخال | اطلب من العميل إعادة المحاولة |
REVOCATION_OF_AUTHORIZATION | دائم | نعم | تم إلغاء تفويض المعاملة | اطلب من العميل استخدام طريقة دفع أخرى |
STOLEN_CARD | دائم | نعم | تم الإبلاغ عن البطاقة كمُسروقة | أظهر للعميل رسالة رفض عامة — لا تكشف عن السبب. اطلب منه استخدام بطاقة أخرى |
SUBSCRIPTION_NOT_ACTIVE | دائم | لا | الاشتراك غير نشط، لذلك لم يتمكن من معالجة الشحنة المتكررة | أعد تفعيل الاشتراك (على سبيل المثال، عن طريق تحديث طريقة الدفع) قبل محاولة الشحنة مرة أخرى |
TRANSACTION_NOT_ALLOWED | دائم | نعم | لا يسمح بإجراء المعاملة لهذه البطاقة أو الحساب | اطلب من العميل الاتصال بمصرفه للسماح بهذا النوع من المعاملات، أو استخدام بطاقة أخرى |
TRANSACTION_NOT_APPROVED | دائم | نعم | لم تتم الموافقة على المعاملة | اطلب من العميل الاتصال بمصرفه أو محاولة بطاقة أخرى |
TRY_AGAIN_LATER | مؤقت | لا | يجب إعادة محاولة المعاملة لاحقًا | مؤقت — أعد المحاولة لاحقًا |
UNKNOWN_ERROR | مؤقت | لا | حدث خطأ غير معروف | أعد المحاولة؛ إذا استمر، اتصل بالدعم |
خطأ المستخدم يشير إلى ما إذا كان يمكن للعميل حل رفض الدفع أم لا. عندما
Yes، يمكن للعميل اتخاذ إجراء لإصلاح المشكلة (على سبيل المثال، إدخال تفاصيل البطاقة الصحيحة). عندما No، يعود الرفض إلى مشاكل على مستوى النظام أو قيود مصرفية لا يمكن للعميل حلها مباشرة.التعامل مع الفشل برمجيًا
اقرأerror_code من payment.failed webhook أو كائن الدفع، واربطه بالإجراء الموصى به أعلاه وقرر ما إذا كانت إعادة المحاولة مجدية. بالنسبة لتجديد الاشتراكات، يتم إعادة محاولة الرفض المؤقت تلقائيًا — انظر إعادة محاولة دفع الاشتراك.
بالنسبة لأخطاء على مستوى API والمنطق التجاري (مثل PAYMENT_NOT_SUCCEEDED أو REFUND_WINDOW_EXPIRED) التي ليست حالات رفض للبطاقات، راجع مرجع رموز الأخطاء.
ذات صلة
Handle Payment Failures
دليل شامل لاكتشاف المعاملات الفاشلة وإظهارها وإعادة محاولة الدفع.
Error Codes
رموز الأخطاء على مستوى API والمنطق التجاري للمعاملات غير الفاشلة.
Subscription Payment Retries
إعادة المحاولات التلقائية لاسترداد حالات الرفض المؤقت لتجديد الاشتراكات.
Subscription Dunning
تسلسلات البريد الإلكتروني التي تسترد حالات الرفض الدائم عن طريق تنبيه بتحديث طريقة الدفع.