处理支付失败

当 payment 失败时，Dodo Payments 会提供标准化的 error_code 和人类可读的 error_message。本指南将介绍如何读取这些字段、判断是否重试，以及如何安全地恢复 payment。

Dodo Payments 如何报告失败

每个失败的 payment object 都包含以下字段：

字段	类型	描述
`status`	string	失败 payment 的 `failed`。其他非成功状态：`cancelled`、`requires_customer_action`、`requires_payment_method`。
`error_code`	string \| null	标准化的 failure reason，例如 `INSUFFICIENT_FUNDS` 或 `PROCESSING_ERROR`。完整列表请参阅 Transaction Failures。
`error_message`	string \| null	面向 merchant 的说明以及建议操作。不应展示给客户。
`retry_attempt`	integer	原始 charge 的 `0`。对于计划中的 subscription renewal retry，为 `1` 或更高。

在 payment 失败之前，error_code 和 error_message 均为 null。请始终先检查 status。

error_message 面向 merchant，可能会暴露与 fraud 相关的原因。切勿将其展示给客户。请改为将 error_code 映射为适合向客户展示的文案（参阅安全地向客户展示 Errors）。

`payment.failed` Webhook

payment.failed webhook 是检测 failure 最可靠的方式。该 event 会将完整的 payment object 包装在 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"
    }
  }
}

最小化的 handler 会读取 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 guide。

决定是否重试：软拒付与硬拒付

error_code 会告诉你是否值得使用相同的支付方式重试。

Decline type	示例	操作
Soft decline	`INSUFFICIENT_FUNDS`、`PROCESSING_ERROR`、`NETWORK_ERROR`、`TRY_AGAIN_LATER`	延迟后重试，或在客户修正其输入后重试。
Hard decline	`STOLEN_CARD`、`LOST_CARD`、`PICKUP_CARD`、`DO_NOT_HONOR`、`FRAUDULENT`、`INVALID_ACCOUNT`	不要使用同一张 card 重试。请客户改用其他 payment method。

完整的 decline type 列表及建议操作请参阅 Transaction Failures。

处理结账期间与续费期间的失败

恢复方式取决于客户是否在场。

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

客户正在主动完成 checkout。请展示清晰的消息，并让客户重试或使用其他 card。

requires_payment_method — 客户从未提供 payment method。这通常是 checkout 中途放弃，而不是 decline。请重新吸引客户完成 payment（参阅 Abandoned Cart Recovery）。
requires_customer_action — 需要额外的 authentication（例如 3DS）。请客户完成 authentication。参阅 3D Secure。

客户当前不在场。当 renewal 失败时，subscription 会进入 on_hold，并触发 subscription.on_hold。如果您的业务设有 grace period，则 subscription 会先进入 past_due（subscription.past_due），并在 grace period 结束前保持 access。

通过 Subscription Payment Retries 开启后，Soft decline 会自动重试（默认关闭）。重试仅适用于计划中的 renewal，不适用于按需 charge。
计划中的 renewal 发生 Hard decline（以及重试次数耗尽）时，会通过 Subscription Dunning 进行恢复，该功能会通过 email 通知客户更新其 payment method。对于按需 charge failure，请参阅 On-Demand Subscriptions。

完整的 on-hold → reactivate 流程请参阅 Subscription Integration Guide。

重试失败的支付

Subscriptions： 启用 Subscription Payment Retries，即可自动恢复 Soft decline。若要立即重试而不是等待计划时间，请通过 dashboard 或 API 使用 Manual Payment Retry。您也可以让客户通过 Update Payment Method API 更新其 payment method，从而触发恢复流程；该操作会收取所有未结清的款项。 一次性 payments： 重新发送 checkout 或 payment_link，让客户可以使用其他 payment method 再次尝试。一次性 payments 不支持自动 retry。

不要使用同一张 card 对 Hard decline 进行重试。Card network 会将重复的 decline 标记为滥用行为，从而损害您的 authorization rate。

安全地向客户展示 Errors

向客户展示友好的消息，绝不要展示原始的 error_code 或面向 merchant 的 error_message。

在由 Dodo Payments 控制的界面（checkout、Customer Portal、dunning email）中，系统已经为您完成了此映射，包括对与 fraud 相关的 decline 回退到通用消息。只有在您自己的 product 中渲染 failure 时，才需要使用下面的映射。

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 的真实原因。展示这些原因可能会向 fraud actor 提供线索。请展示通用的 decline 消息，并且仅在内部记录具体的 error_code。

Transaction Failures

每个 decline code、其 type 以及建议操作。

Error Codes

不是 card decline 的 API 和 business-logic errors。

Subscription Payment Retries

subscription renewal 中 Soft decline 的自动恢复。

Subscription Dunning

用于恢复 Hard decline 的 email sequence。

Payment Webhooks

payment event 的完整 payload schema。

Testing Failures

用于模拟 decline 和 renewal failure 的 test card。

Integration Guides

Billing Deconstructions

Cookbooks

Dodo Payments 如何报告失败

`payment.failed` Webhook

决定是否重试：软拒付与硬拒付

处理结账期间与续费期间的失败

重试失败的支付

安全地向客户展示 Errors

相关内容

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

​Dodo Payments 如何报告失败

​payment.failed Webhook

​决定是否重试：软拒付与硬拒付

​处理结账期间与续费期间的失败

​重试失败的支付

​安全地向客户展示 Errors

​相关内容

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

Dodo Payments 如何报告失败

`payment.failed` Webhook

决定是否重试：软拒付与硬拒付

处理结账期间与续费期间的失败

重试失败的支付

安全地向客户展示 Errors

相关内容