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

عند فشل دفعة، يخبرك 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 أولًا، ثم اقرأ حقول الخطأ.

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 renewal — Dodo retries soft declines for you
      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 renewal — Dodo retries soft declines for you
            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` و`DO_NOT_HONOR` و`FRAUDULENT`).	لا تعاود المحاولة باستخدام البطاقة نفسها. اطلب من العميل استخدام طريقة دفع مختلفة.

يسرد مرجع Transaction Failures نوع الرفض والإجراء الموصى به لكل error_code.

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

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

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

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

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

العميل غير حاضر، لذلك لا يمكنك مطالبته باتخاذ إجراء في الوقت الفعلي. عند فشل التجديد، ينتقل الاشتراك إلى on_hold ويتم تشغيل subscription.on_hold.

تتم إعادة محاولة حالات الرفض المؤقت تلقائيًا بواسطة إعادة محاولات دفع الاشتراك.
من الأفضل استرداد حالات الرفض النهائي (وإعادة المحاولات التي استُنفدت) باستخدام متابعة تحصيل الاشتراك، التي ترسل إلى العميل رسالة بريد إلكتروني لتحديث طريقة الدفع.

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

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

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

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

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

اعرض للعملاء رسالة ودية — وليس error_code الخام مطلقًا.

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`

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

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

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

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

ذات صلة