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

عند فشل دفعة، يخبرك 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	شرح مفهوم للفشل، مكتوب لك وليس لعميلك. بالنسبة إلى `error_code` موحّد، يكون هذا عنوانًا رئيسيًا بالإضافة إلى الإجراء المقترح، وليس النص الخام من معالج الدفع.
`retry_attempt`	integer	`0` للخصم الأصلي. يحدد `1` أو أعلى إعادة محاولة مجدولة لتجديد اشتراك.

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

error_message من merchant API هو نص موجّه للتاجر. ويمكن أن يذكر السبب الحقيقي للرفض، بما في ذلك الأسباب المرتبطة بالاحتيال، لذلك لا تعرضه مباشرةً للعميل مطلقًا. اربط 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 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 الخام مطلقًا، ولا 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`

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

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

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

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

ذات صلة