处理支付失败

当付款失败时，Dodo Payments 会通过标准化的 error_code 和人类可读的 error_message 告诉您失败原因。此指南展示如何读取这些字段、决定是否值得重试，并在不向客户暴露敏感信息的情况下恢复付款。

Dodo Payments 如何报告失败

每个失败的支付——无论是一次性结账还是订阅续订——都会在支付对象上携带相同的失败字段：

Field	Type	Description
`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，然后读取错误字段。

来自 merchant API 的 error_message 是面向商户的文案。它可能会指出拒付的真实原因，包括与欺诈相关的原因，因此绝不要直接向客户展示。请改为将 error_code 映射为你自己的、对客户安全的文案，如 Surface Errors to Customers Safely 中所示。

`payment.failed` Webhook

检测失败最可靠的方式是 payment.failed webhook。该事件会将完整的支付对象封装在 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 guide。

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

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

Decline type	What it means	What to do
Soft decline	暂时性或可纠正的拒付（例如 `INSUFFICIENT_FUNDS`、`PROCESSING_ERROR`、`NETWORK_ERROR`、`TRY_AGAIN_LATER`）。	延迟一段时间后重试，或在客户修正输入信息后重试，可能会成功。
Hard decline	终止性拒付（例如 `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 — 客户从未提供支付方式：他们没有输入卡片详细信息，或系统提示他们提供支付方式后却没有采取任何操作。这通常是结账中途放弃，而不是拒付 — 重新吸引客户完成支付（请参阅 Abandoned Cart Recovery）。
requires_customer_action — 需要额外身份验证（例如 3DS）；请客户完成验证。请参阅 3D Secure handling。

客户不在场，因此你无法实时提示他们。续费失败时，订阅会转为 on_hold，并触发 subscription.on_hold。

软拒付会由 Subscription Payment Retries 自动重新尝试。
硬拒付（以及重试次数耗尽的情况）最好通过 Subscription Dunning 恢复；该功能会发送电子邮件，要求客户更新支付方式。

完整的暂停 → 重新激活流程请参阅 Subscription Integration Guide。

重试失败的支付

**订阅：**启用 Subscription Payment Retries，无需进行集成开发即可恢复软拒付。你也可以让客户通过 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

支付事件的完整 payload schema。

Testing Failures

用于模拟拒付和续费失败的测试卡。

Integration Guides

Billing Deconstructions

Cookbooks

Dodo Payments 如何报告失败

`payment.failed` Webhook

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

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

重试失败的支付

安全地向客户展示错误

相关内容

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

​Dodo Payments 如何报告失败

​payment.failed Webhook

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

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

​重试失败的支付

​安全地向客户展示错误

​相关内容

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

Dodo Payments 如何报告失败

`payment.failed` Webhook

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

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

重试失败的支付

安全地向客户展示错误

相关内容