معالجة حالات فشل الدفع

عند فشل عملية دفع، يوفر Dodo Payments رمز فشل موحدًا error_code ووصفًا مقروءًا للبشر error_message. يوضح هذا الدليل كيفية قراءة هذه الحقول، وتحديد ما إذا كان ينبغي إعادة المحاولة، واستعادة عملية الدفع بأمان.

كيف يُبلغ Dodo Payments عن الفشل

تحتوي كل عملية دفع فاشلة على هذه الحقول في كائن الدفع:

الحقل	النوع	الوصف
`status`	string	`failed` لعملية دفع فاشلة. الحالات الأخرى غير الناجحة: `cancelled` و`requires_customer_action` و`requires_payment_method`.
`error_code`	string \| null	سبب الفشل الموحد، مثل `INSUFFICIENT_FUNDS` أو `PROCESSING_ERROR`. راجع Transaction Failures للاطلاع على القائمة الكاملة.
`error_message`	string \| null	شرح موجّه إلى التاجر مع الإجراء الموصى به. غير مخصص للعملاء.
`retry_attempt`	integer	`0` لعملية الخصم الأصلية. `1` أو أعلى لمحاولات تجديد الاشتراك المجدولة.

يكون كل من error_code وerror_message بقيمة null حتى تفشل عملية الدفع. تحقق دائمًا من status أولًا.

إن error_message موجّه إلى التاجر وقد يكشف أسبابًا مرتبطة بالاحتيال. لا تعرضه للعملاء مطلقًا. بدلاً من ذلك، اربط error_code بصياغة آمنة للعملاء (راجع عرض الأخطاء للعملاء بأمان).

Webhook الخاص بـ `payment.failed`

يُعد webhook ‏payment.failed الطريقة الأكثر موثوقية لاكتشاف الفشل. يغلّف الحدث كائن الدفع الكامل في data:

payment.failed payload

{
  "business_id": "bus_P3SXLcppjXgagmHS",
  "type": "payment.failed",
  "timestamp": "2025-08-04T05:36:41.609359Z",
  "data": {
    "payload_type": "Payment",
    "payment_id": "pay_2IjeQm4hqU6RA4Z4kwDee",
    "status": "failed",
    "error_code": "PROCESSING_ERROR",
    "error_message": "An error occurred while processing your card. Try again in a little bit.",
    "retry_attempt": 0,
    "subscription_id": null,
    "currency": "USD",
    "total_amount": 400,
    "payment_method": "card",
    "card_last_four": "0119",
    "card_network": "VISA",
    "payment_link": "https://test.checkout.dodopayments.com/cbq",
    "customer": {
      "customer_id": "cus_8VbC6JDZzPEqfB",
      "email": "test@acme.com",
      "name": "Test user"
    }
  }
}

يقرأ المعالج البسيط error_code ويوجّه التدفق بناءً عليه:

import { Webhook } from "standardwebhooks";
import express from "express";

const app = express();
// Mount the raw body parser so the exact payload is available for verification
app.use(express.raw({ type: "application/json" }));

const webhook = new Webhook(process.env.DODO_PAYMENTS_WEBHOOK_KEY);

app.post("/webhooks/dodo", async (req, res) => {
  // Verify the signature against the raw body before trusting the payload
  const payload = req.body.toString();
  await webhook.verify(payload, req.headers);

  const event = JSON.parse(payload);

  if (event.type === "payment.failed") {
    const payment = event.data;

    console.log(
      `Payment ${payment.payment_id} failed: ${payment.error_code} (${payment.error_message})`
    );

    if (payment.subscription_id) {
      // Subscription payment. If Payment Retries is on, Dodo retries failed renewals.
      // On-demand charges are never retried automatically: handle those yourself.
      await flagSubscriptionPaymentIssue(payment.subscription_id, payment.error_code);
    } else {
      // One-time payment — prompt the customer to try again
      await notifyCustomerOfFailedPayment(payment.customer.customer_id, payment.error_code);
    }
  }

  res.json({ received: true });
});

import os
from fastapi import FastAPI, Request
from standardwebhooks import Webhook

app = FastAPI()
webhook = Webhook(os.environ["DODO_PAYMENTS_WEBHOOK_KEY"])

@app.post("/webhooks/dodo")
async def handle_webhook(request: Request):
    # Verify the signature before trusting the payload
    payload = await request.body()
    webhook.verify(payload, dict(request.headers))

    event = await request.json()

    if event["type"] == "payment.failed":
        payment = event["data"]

        print(
            f"Payment {payment['payment_id']} failed: "
            f"{payment['error_code']} ({payment['error_message']})"
        )

        if payment["subscription_id"]:
            # Subscription payment. If Payment Retries is on, Dodo retries failed renewals.
            # On-demand charges are never retried automatically: handle those yourself.
            flag_subscription_payment_issue(payment["subscription_id"], payment["error_code"])
        else:
            # One-time payment — prompt the customer to try again
            notify_customer_of_failed_payment(payment["customer"]["customer_id"], payment["error_code"])

    return {"received": True}

تحقق دائمًا من توقيع webhook قبل معالجته. راجع دليل Webhooks للاطلاع على الإعداد الكامل، بما في ذلك التحقق من التوقيع وضمان عدم التكرار.

تحديد ما إذا كنت ستعيد المحاولة: حالات الرفض المؤقتة مقابل النهائية

يخبرك error_code ما إذا كانت إعادة المحاولة باستخدام طريقة الدفع نفسها تستحق العناء.

نوع الرفض	أمثلة	الإجراء
رفض مؤقت	`INSUFFICIENT_FUNDS` و`PROCESSING_ERROR` و`NETWORK_ERROR` و`TRY_AGAIN_LATER`	أعد المحاولة بعد فترة تأخير أو بعد تصحيح العميل لبياناته.
رفض نهائي	`STOLEN_CARD` و`LOST_CARD` و`PICKUP_CARD` و`DO_NOT_HONOR` و`FRAUDULENT` و`INVALID_ACCOUNT`	لا تعاود المحاولة باستخدام البطاقة نفسها. اطلب من العميل استخدام طريقة دفع مختلفة.

راجع Transaction Failures للاطلاع على القائمة الكاملة لأنواع الرفض والإجراءات الموصى بها.

معالجة حالات الفشل عند الدفع مقابل التجديد

تعتمد طريقة الاسترداد على ما إذا كان العميل حاضرًا.

At checkout (customer present)
On subscription renewal (customer not present)

العميل يُجري عملية الدفع حاليًا. اعرض رسالة واضحة واسمح له بإعادة المحاولة أو استخدام بطاقة أخرى.

requires_payment_method — لم يقدّم العميل طريقة دفع مطلقًا. عادةً ما يعني هذا التخلي عن عملية الدفع، وليس رفضًا. أعد إشراك العميل لإكمال الدفع (راجع استعادة السلات المتروكة).
requires_customer_action — يلزم إجراء مصادقة إضافية (مثل 3DS). اطلب من العميل إكمالها. راجع 3D Secure.

العميل غير حاضر. عند فشل عملية التجديد، ينتقل الاشتراك إلى on_hold ويتم تشغيل subscription.on_hold. إذا كان نشاطك التجاري يوفّر فترة سماح، ينتقل الاشتراك أولًا إلى past_due ‏(subscription.past_due) ويظل الوصول متاحًا حتى انتهاء فترة السماح.

تتم إعادة محاولة حالات الرفض المؤقت تلقائيًا إذا فعّلت إعادة محاولات دفع الاشتراكات (وهي معطّلة افتراضيًا). تغطي عمليات إعادة المحاولة التجديدات المجدولة فقط، وليس عمليات الخصم عند الطلب.
تتم استعادة حالات الرفض النهائي (والمحاولات المستنفدة) في التجديدات المجدولة باستخدام Subscription Dunning، الذي يرسل إلى العميل رسالة بريد إلكتروني لتحديث طريقة الدفع. بالنسبة إلى حالات فشل الخصم عند الطلب، راجع On-Demand Subscriptions.

راجع Subscription Integration Guide للاطلاع على التدفق الكامل من التعليق إلى إعادة التفعيل.

إعادة محاولة دفعة فاشلة

الاشتراكات: فعّل إعادة محاولات دفع الاشتراكات لاستعادة حالات الرفض المؤقت تلقائيًا. لإعادة المحاولة فورًا بدلًا من الانتظار وفق الجدول، استخدم Manual Payment Retry من لوحة المعلومات أو API. يمكنك أيضًا بدء الاستعادة بأن يحدّث العميل طريقة الدفع عبر Update Payment Method API، الذي يخصم أي مستحقات معلّقة. المدفوعات لمرة واحدة: أعد إرسال صفحة الدفع أو payment_link حتى يتمكن العميل من المحاولة مجددًا باستخدام طريقة مختلفة. لا توجد إعادة محاولة تلقائية للمدفوعات لمرة واحدة.

لا تعاود محاولة حالات الرفض النهائي باستخدام البطاقة نفسها. تعتبر شبكات البطاقات تكرار حالات الرفض سلوكًا مسيئًا، مما يضر بمعدل التفويض لديك.

عرض الأخطاء للعملاء بأمان

اعرض للعملاء رسالة ودية، ولا تعرض مطلقًا error_code الخام أو error_message الموجّه إلى التاجر.

في الأسطح التي يتحكم فيها Dodo Payments (صفحة الدفع وCustomer Portal ورسائل البريد الإلكتروني الخاصة بالتحصيل)، تتم هذه المطابقة نيابةً عنك، بما في ذلك الرجوع إلى رسالة عامة لحالات الرفض المرتبطة بالاحتيال. تحتاج إلى المطابقة أدناه فقط عند عرض حالات الفشل في منتجك الخاص.

Customer-facing messaging

const CUSTOMER_MESSAGES = {
  INSUFFICIENT_FUNDS: "Your card has insufficient funds. Please use another card.",
  EXPIRED_CARD: "Your card has expired. Please use a card with a valid expiry date.",
  INCORRECT_CVC: "The security code (CVC) is incorrect. Please re-enter it.",
};

function customerMessage(errorCode) {
  // Sensitive declines must never reveal the real reason
  const SENSITIVE = ["STOLEN_CARD", "LOST_CARD", "PICKUP_CARD", "FRAUDULENT"];
  if (SENSITIVE.includes(errorCode)) {
    return "Your card was declined. Please contact your bank or use another card.";
  }
  return CUSTOMER_MESSAGES[errorCode] ?? "Your payment could not be processed. Please try another card.";
}

لا تكشف أبدًا السبب الحقيقي للحالات STOLEN_CARD أو LOST_CARD أو PICKUP_CARD أو FRAUDULENT. قد يؤدي عرض هذه الأسباب إلى تنبيه جهة احتيالية. اعرض رسالة عامة تفيد بالرفض، وسجّل error_code المحدد داخليًا فقط.

ذو صلة

Transaction Failures

كل رمز رفض ونوعه والإجراء الموصى به.

Error Codes

أخطاء API ومنطق الأعمال التي لا تُعد حالات رفض للبطاقات.

Subscription Payment Retries

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

Subscription Dunning

تسلسلات البريد الإلكتروني التي تستعيد حالات الرفض النهائي.

Payment Webhooks

مخطط الحمولة الكامل لأحداث الدفع.

Testing Failures

بطاقات اختبار تحاكي حالات الرفض وفشل التجديد.

Integration Guides

Billing Deconstructions

Cookbooks

كيف يُبلغ Dodo Payments عن الفشل

Webhook الخاص بـ `payment.failed`

تحديد ما إذا كنت ستعيد المحاولة: حالات الرفض المؤقتة مقابل النهائية

معالجة حالات الفشل عند الدفع مقابل التجديد

إعادة محاولة دفعة فاشلة

عرض الأخطاء للعملاء بأمان

ذو صلة

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

​كيف يُبلغ Dodo Payments عن الفشل

​Webhook الخاص بـ payment.failed

​تحديد ما إذا كنت ستعيد المحاولة: حالات الرفض المؤقتة مقابل النهائية

​معالجة حالات الفشل عند الدفع مقابل التجديد

​إعادة محاولة دفعة فاشلة

​عرض الأخطاء للعملاء بأمان

​ذو صلة

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

كيف يُبلغ Dodo Payments عن الفشل

Webhook الخاص بـ `payment.failed`

تحديد ما إذا كنت ستعيد المحاولة: حالات الرفض المؤقتة مقابل النهائية

معالجة حالات الفشل عند الدفع مقابل التجديد

إعادة محاولة دفعة فاشلة

عرض الأخطاء للعملاء بأمان

ذو صلة