> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 交易失败

> 了解不同的交易失败原因以及如何在 Dodo Payments API 中处理它们。

## 概述

Dodo Payments API 提供详细的交易失败原因，帮助您理解为什么支付尝试未成功。这些失败原因在不同的支付方式和提供商之间是标准化的，使您能够在应用程序中实现一致的错误处理。

每个交易失败响应包括：

* 一个特定的失败原因代码
* 一个可读的错误信息
* 可用时关于失败的额外上下文
* 错误是否可以由用户纠正或需要系统干预

理解这些失败原因对于以下方面至关重要：

* 向客户提供清晰的反馈
* 实施适当的重试逻辑
* 优雅地处理不同的失败场景
* 维护可靠的支付处理系统

## 交易失败原因

下表列出了所有可能的交易失败原因、它们的含义以及它们是否是用户可纠正的错误。

| 故障代码                               | 是否为用户错误 | 描述             |
| ---------------------------------- | ------- | -------------- |
| `AUTHENTICATION_FAILURE`           | 是       | 在交易过程中身份验证失败   |
| `AUTHENTICATION_REQUIRED`          | 是       | 需要额外身份验证以完成交易  |
| `AUTHENTICATION_TIMEOUT`           | 是       | 身份验证过程超时       |
| `CARD_DECLINED`                    | 否       | 发卡银行拒绝了该卡      |
| `CARD_NOT_ACTIVATED`               | 是       | 持卡人尚未激活该卡      |
| `CARD_VELOCITY_EXCEEDED`           | 是       | 短时间内尝试了过多交易    |
| `CUSTOMER_CANCELLED`               | 是       | 客户取消了交易        |
| `DO_NOT_HONOR`                     | 否       | 发卡银行拒绝了该交易     |
| `EXPIRED_CARD`                     | 是       | 该卡已过期          |
| `FRAUDULENT`                       | 是       | 交易被标记为可能存在欺诈行为 |
| `GENERIC_DECLINE`                  | 否       | 交易因未说明的原因被拒绝   |
| `INCORRECT_CVC`                    | 是       | 提供的 CVC 码不正确   |
| `INCORRECT_NUMBER`                 | 是       | 卡号输入错误         |
| `INSUFFICIENT_FUNDS`               | 是       | 账户资金不足，无法完成交易  |
| `INVALID_ACCOUNT`                  | 是       | 提供的账户信息无效      |
| `INVALID_AMOUNT`                   | 是       | 交易金额无效         |
| `INVALID_CARD_NUMBER`              | 是       | 卡号格式无效         |
| `INVALID_CARD_OWNER`               | 是       | 卡片持有人信息无效      |
| `INVALID_CVC`                      | 是       | CVC 格式无效       |
| `INVALID_EXPIRY_YEAR`              | 是       | 卡片失效年份无效       |
| `INVALID_PIN`                      | 是       | 提供的 PIN 不正确    |
| `INVALID_REQUEST`                  | 是       | 交易请求包含无效数据     |
| `INVALID_UPI_ID`                   | 是       | 提供的 UPI ID 无效  |
| `LIMIT_EXCEEDED`                   | 是       | 交易超出了卡片或账户限额   |
| `LIVE_MODE_TEST_CARD`              | 是       | 在实模式中使用了测试卡    |
| `LOST_CARD`                        | 是       | 该卡已被报告为丢失      |
| `MANDATE_INVALID`                  | 是       | 支付授权无效         |
| `MANDATE_REQUIRED`                 | 是       | 此交易需要授权        |
| `MANDATE_REQUIRED_SYSTEM`          | 否       | 系统要求此类交易必须有授权  |
| `NETWORK_ERROR`                    | 否       | 交易过程中发生网络错误    |
| `NETWORK_TIMEOUT`                  | 否       | 网络请求超时         |
| `ORDER_CREATION_FAILED`            | 否       | 无法为交易创建订单      |
| `PAYMENT_METHOD_PROVIDER_DECLINED` | 是       | 支付方式提供商拒绝了交易   |
| `PAYMENT_METHOD_UNSUPPORTED`       | 是       | 该交易不支持所选支付方式   |
| `PICKUP_CARD`                      | 是       | 该卡已被报告为被盗并应收回  |
| `PROCESSING_ERROR`                 | 否       | 交易处理过程中发生错误    |
| `PROVIDER_UNSUPPORTED`             | 否       | 支付提供商不支持此类交易   |
| `REENTER_TRANSACTION`              | 是       | 交易需要重新输入       |
| `REVOCATION_OF_AUTHORIZATION`      | 是       | 交易授权被撤销        |
| `STOLEN_CARD`                      | 是       | 该卡已被报告为被盗      |
| `TRANSACTION_NOT_ALLOWED`          | 是       | 此卡或账户不允许该交易    |
| `TRANSACTION_NOT_APPROVED`         | 是       | 交易未被批准         |
| `TRY_AGAIN_LATER`                  | 否       | 应该稍后重试该交易      |
| `UNKNOWN_ERROR`                    | 否       | 发生未知错误         |

<Note>
  **用户错误** 表示付款拒绝是否可由客户自行解决。 当 `true` 时，客户可以采取措施解决问题（例如输入正确的卡信息）。 当 `false` 时，拒付是由于系统级问题或银行限制，客户无法解决。
</Note>

## 支持

如需有关交易失败或集成问题的更多帮助，请通过 [support@dodopayments.com](mailto:support@dodopayments.com) 联系我们的支持团队.

<Card title="Handle Payment Failures" icon="screwdriver-wrench" href="/developer-resources/handle-payment-failures">
  **绝不要向客户透露 `STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, 或 `FRAUDULENT` 的真实原因。** 公开这些信息可能会警告欺诈行为者。始终向客户展示通用的拒绝消息（例如，*“您的卡已被拒绝。请联系您的银行或使用其他卡。”*），具体代码仅供内部记录。
</Card>

## 交易失败原因

下表列出了每个失败代码、拒绝类型、客户是否可以解决、描述以及推荐的操作。

| 失败代码                               | 类型 | 用户错误 | 描述                                       | 推荐操作                           |
| ---------------------------------- | -- | ---- | ---------------------------------------- | ------------------------------ |
| `AUTHENTICATION_FAILURE`           | 软  | 是    | 交易过程中认证失败                                | 请客户重试并完成3DS认证，或使用另一张卡          |
| `AUTHENTICATION_REQUIRED`          | 软  | 是    | 需要额外认证以完成交易                              | 提示客户完成3DS认证。对于订阅续期，请客户返回并认证    |
| `AUTHENTICATION_TIMEOUT`           | 软  | 是    | 认证过程超时                                   | 请客户重试并及时完成认证                   |
| `CARD_DECLINED`                    | 软  | 否    | 发卡行在没有具体原因的情况下拒绝了卡（通用拒绝）                 | 请客户重试，联系他们的银行，或使用另一张卡          |
| `CARD_NOT_ACTIVATED`               | 软  | 是    | 持卡人未激活卡                                  | 请客户与银行激活卡，然后重试                 |
| `CARD_VELOCITY_EXCEEDED`           | 软  | 是    | 短时间内尝试了太多交易                              | 请客户稍后重试，或联系银行了解限制              |
| `CUSTOMER_CANCELLED`               | 软  | 是    | 客户取消了交易                                  | 让客户在准备好后重新开始结账                 |
| `DO_NOT_HONOR`                     | 硬  | 否    | 发卡行明确拒绝了交易（ISO 8583代码05 — 不予承兑）；网络将其视为终端 | 请客户联系他们的银行；不要重试同一张卡            |
| `EXPIRED_CARD`                     | 硬  | 是    | 卡已过期                                     | 请客户使用有效到期日期的卡                  |
| `FRAUDULENT`                       | 硬  | 是    | 交易被标记为潜在欺诈                               | 向客户显示通用拒绝消息 — 不要透露原因。请他们使用另一张卡 |
| `GENERIC_DECLINE`                  | 软  | 否    | 交易因未指定原因被拒绝                              | 请客户联系他们的银行或尝试另一张卡              |
| `INCORRECT_CVC`                    | 软  | 是    | 提供的CVC代码不正确                              | 请客户重新输入正确的CVC                  |
| `INCORRECT_NUMBER`                 | 软  | 是    | 卡号输入错误                                   | 请客户重新输入正确的卡号                   |
| `INSUFFICIENT_FUNDS`               | 软  | 是    | 账户资金不足，无法完成交易                            | 请客户使用其他付款方式或在有资金时重试            |
| `INVALID_ACCOUNT`                  | 硬  | 是    | 提供的账户详细信息无效                              | 请客户联系他们的银行或使用另一张卡              |
| `INVALID_AMOUNT`                   | 软  | 是    | 交易金额无效                                   | 和客户核实金额及任何购买限制                 |
| `INVALID_CARD_NUMBER`              | 软  | 是    | 卡号格式无效                                   | 请客户重新输入有效的卡号                   |
| `INVALID_CARD_OWNER`               | 软  | 是    | 持卡人信息无效                                  | 请客户更正持卡人姓名                     |
| `INVALID_CVC`                      | 软  | 是    | CVC格式无效                                  | 请客户重新输入有效的CVC                  |
| `INVALID_EXPIRY_YEAR`              | 软  | 是    | 卡的到期年份无效                                 | 请客户输入有效的到期日期                   |
| `INVALID_PIN`                      | 软  | 是    | 提供的PIN不正确                                | 请客户重新输入正确的PIN                  |
| `INVALID_REQUEST`                  | 软  | 是    | 交易请求包含无效数据                               | 检查支付请求字段，并使用有效数据重新提交           |
| `INVALID_UPI_ID`                   | 软  | 是    | 提供的UPI ID无效                              | 请客户输入有效的UPI ID                 |
| `LIMIT_EXCEEDED`                   | 软  | 是    | 交易超出卡或账户限额                               | 请客户联系他们的银行了解限制，或使用其他方法         |
| `LIVE_MODE_TEST_CARD`              | 硬  | 是    | 在现场模式中使用了测试卡                             | 使用真实卡 — 重试测试卡在现场模式下总是失败        |
| `LOST_CARD`                        | 硬  | 是    | 卡被报告为丢失                                  | 向客户显示通用拒绝消息 — 不要透露原因。请他们使用另一张卡 |
| `MANDATE_INVALID`                  | 软  | 是    | 支付授权无效                                   | 请客户重新设置支付授权                    |
| `MANDATE_REQUIRED`                 | 软  | 是    | 该交易需要授权                                  | 设置授权，并请客户在收费前授权                |
| `MANDATE_REQUIRED_SYSTEM`          | 硬  | 否    | 系统需要该交易类型的授权                             | 确保在收费前完成授权设置流程                 |
| `NETWORK_ERROR`                    | 软  | 否    | 交易过程中发生网络错误                              | 是暂时性的 — 稍后重试交易                 |
| `NETWORK_TIMEOUT`                  | 软  | 否    | 网络请求超时                                   | 是暂时性的 — 稍后重试交易                 |
| `ORDER_ALREADY_EXISTS`             | 软  | 否    | 该交易订单已存在（重复订单创建）                         | 在重试前检查现有订单状态；如果持续发生，请联系支持      |
| `ORDER_CREATION_FAILED`            | 软  | 否    | 创建交易订单失败                                 | 是暂时性/系统错误 — 重试支付；如果持续发生，请联系支持  |
| `PAYMENT_METHOD_PROVIDER_DECLINED` | 硬  | 是    | 支付方式提供者拒绝了交易                             | 请客户联系他们的提供者或使用其他支付方式           |
| `PAYMENT_METHOD_UNSUPPORTED`       | 硬  | 是    | 此交易不支持支付方式                               | 请客户使用支持的支付方式                   |
| `PICKUP_CARD`                      | 硬  | 是    | 卡被报告为丢失或被盗，已标记为取回                        | 向客户显示通用拒绝消息 — 不要透露原因。请他们使用另一张卡 |
| `PROCESSING_ERROR`                 | 软  | 否    | 处理中发生错误                                  | 是暂时性的 — 重试支付；如果持续发生，请客户联系他们的银行 |
| `PROVIDER_UNSUPPORTED`             | 硬  | 否    | 支付提供商不支持此交易类型                            | 请客户使用其他支付方式                    |
| `REENTER_TRANSACTION`              | 软  | 是    | 需要重新输入交易                                 | 请客户重试支付                        |
| `REVOCATION_OF_AUTHORIZATION`      | 硬  | 是    | 交易授权被撤销                                  | 请客户使用其他支付方式                    |
| `STOLEN_CARD`                      | 硬  | 是    | 卡被报告为被盗                                  | 向客户显示通用拒绝消息 — 不要透露原因。请他们使用另一张卡 |
| `SUBSCRIPTION_NOT_ACTIVE`          | 硬  | 否    | 订阅未激活，无法处理定期费用                           | 重新激活订阅（例如，通过更新支付方式），然后再尝试收费    |
| `TRANSACTION_NOT_ALLOWED`          | 硬  | 是    | 此卡或账户不允许交易                               | 请客户联系他们的银行以允许此交易类型，或使用另一张卡     |
| `TRANSACTION_NOT_APPROVED`         | 硬  | 是    | 交易未获批准                                   | 请客户联系他们的银行或尝试另一张卡              |
| `TRY_AGAIN_LATER`                  | 软  | 否    | 交易应稍后重试                                  | 是暂时性的 — 稍后重试支付                 |
| `UNKNOWN_ERROR`                    | 软  | 否    | 发生未知错误                                   | 重试支付；如果持续发生，请联系支持              |

<Note>
  **用户错误** 表示支付拒绝是否可以通过客户解决。当 `Yes` 时，客户可以采取行动解决问题（例如，输入正确的卡详细信息）。当 `No` 时，拒绝是由于系统级别问题或银行限制，客户无法直接解决。
</Note>

<Info>
  当发卡行的风险引擎将持卡人标记为高风险客户时，卡也可能被拒绝 — 独立于商家或交易细节。此类拒绝通常显示为通用代码，如 `DO_NOT_HONOR`, `GENERIC_DECLINE`, `CARD_DECLINED`, `TRANSACTION_NOT_APPROVED`, 或 `FRAUDULENT`。在这些情况下，银行不会共享具体原因，Dodo Payments或商家无法覆盖该决定。请客户联系他们的银行解决该标记，或使用不同的卡或支付方式。
</Info>

## 程序化处理失败

从 `payment.failed` webhook 或支付对象中读取 `error_code`，将其映射到上述推荐操作，并决定是否重试。对于订阅续期，系统会自动重试软拒绝 — 请参阅 [订阅支付重试](/features/recovery/payment-retries)。

对于API层和业务逻辑错误（如 `PAYMENT_NOT_SUCCEEDED` 或 `REFUND_WINDOW_EXPIRED`）而非卡拒绝，请参阅 [错误代码](/api-reference/error-codes) 参考。

## 相关

<CardGroup cols={2}>
  <Card title="Handle Payment Failures" icon="screwdriver-wrench" href="/developer-resources/handle-payment-failures">
    检测、展示和重试支付失败的端到端指南。
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/api-reference/error-codes">
    非拒绝失败的API和业务逻辑错误代码。
  </Card>

  <Card title="Subscription Payment Retries" icon="arrow-rotate-right" href="/features/recovery/payment-retries">
    通过自动重试恢复订阅续期中的软拒绝。
  </Card>

  <Card title="Subscription Dunning" icon="repeat" href="/features/recovery/subscription-dunning">
    通过提示更新支付方式来恢复硬拒绝的电子邮件序列。
  </Card>
</CardGroup>

## 支持

如果需要更多关于交易失败或集成问题的帮助，请通过 [support@dodopayments.com](mailto:support@dodopayments.com) 联系我们的支持团队。