> ## 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.

# Transaction Failures

> Understand every Dodo Payments transaction failure code, whether it is a soft or hard decline, and the recommended action to recover the payment.

## Overview

Dodo Payments returns a detailed failure reason whenever a payment attempt is unsuccessful. These reasons are standardized across payment methods and providers, so you can implement consistent handling in your application.

When a payment fails, the `payment.failed` webhook and the payment object expose:

* `error_code` — a standardized failure reason from the table below.
* `error_message` — a human-readable explanation.
* `retry_attempt` — `0` for the original charge, `1` or higher for each scheduled subscription renewal retry.

Understanding these failure reasons lets you give customers clear feedback, decide whether a retry is worthwhile, and recover more revenue.

<Card title="Handle Payment Failures" icon="screwdriver-wrench" href="/developer-resources/handle-payment-failures">
  A step-by-step developer guide for reading these codes from webhooks and the API, surfacing them to customers, and deciding when to retry.
</Card>

## Soft vs. Hard Declines

Every failure code falls into one of two categories. This distinction drives whether you should retry the same payment method or ask the customer for a new one.

| Decline type     | What it means                                                                                                   | What to do                                                                                                | Examples                                                                                                                                     |
| ---------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Soft decline** | Temporary or correctable — the same card can succeed on a later attempt or once the customer fixes their input. | Safe to retry (after a delay, or once the customer corrects their details).                               | `INSUFFICIENT_FUNDS`, `GENERIC_DECLINE`, `CARD_VELOCITY_EXCEEDED`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `NETWORK_TIMEOUT`, `TRY_AGAIN_LATER` |
| **Hard decline** | Terminal — retrying the same card will not change the outcome.                                                  | Do **not** retry the same card. Ask the customer to use a different payment method or contact their bank. | `STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`                                                   |

For subscription renewals, Dodo Payments applies this distinction automatically: soft declines are re-attempted by [Subscription Payment Retries](/features/recovery/payment-retries), while hard declines end the retry chain immediately and are best handled with [Subscription Dunning](/features/recovery/subscription-dunning).

<Warning>
  **Never reveal the real reason for `STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, or `FRAUDULENT` to the customer.** Surfacing these can tip off a fraudulent actor. Always show the customer a generic decline message (for example, *"Your card was declined. Please contact your bank or use another card."*) and only log the specific code internally.
</Warning>

## Transaction Failure Reasons

The following table lists every failure code, its decline type, whether the customer can resolve it, a description, and the recommended action.

| Failure Code                       | Type | User Error | Description                                                                                                            | Recommended Action                                                                                                         |
| ---------------------------------- | ---- | ---------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `AUTHENTICATION_FAILURE`           | Soft | Yes        | Authentication failed during the transaction                                                                           | Ask the customer to retry and complete 3DS authentication, or use another card                                             |
| `AUTHENTICATION_REQUIRED`          | Soft | Yes        | Additional authentication is needed to complete the transaction                                                        | Prompt the customer to complete 3DS authentication. For subscription renewals, ask the customer to return and authenticate |
| `AUTHENTICATION_TIMEOUT`           | Soft | Yes        | The authentication process timed out                                                                                   | Ask the customer to retry and complete authentication promptly                                                             |
| `CARD_DECLINED`                    | Soft | No         | The card was declined by the issuing bank without a specific reason (generic decline)                                  | Ask the customer to retry, contact their bank, or use another card                                                         |
| `CARD_NOT_ACTIVATED`               | Soft | Yes        | The card has not been activated by the cardholder                                                                      | Ask the customer to activate the card with their bank, then retry                                                          |
| `CARD_VELOCITY_EXCEEDED`           | Soft | Yes        | Too many transactions attempted in a short period                                                                      | Ask the customer to wait and retry later, or contact their bank about limits                                               |
| `CUSTOMER_CANCELLED`               | Soft | Yes        | The customer cancelled the transaction                                                                                 | Let the customer restart checkout when they are ready                                                                      |
| `DO_NOT_HONOR`                     | Hard | No         | The issuing bank explicitly refused the transaction (ISO 8583 code 05 — do not honor); networks treat this as terminal | Ask the customer to contact their bank; do not retry the same card                                                         |
| `EXPIRED_CARD`                     | Hard | Yes        | The card has expired                                                                                                   | Ask the customer to use a card with a valid expiry date                                                                    |
| `FRAUDULENT`                       | Hard | Yes        | The transaction was flagged as potentially fraudulent                                                                  | Show the customer a generic decline message — do not reveal the reason. Ask them to use another card                       |
| `GENERIC_DECLINE`                  | Soft | No         | The transaction was declined for an unspecified reason                                                                 | Ask the customer to contact their bank or try another card                                                                 |
| `INCORRECT_CVC`                    | Soft | Yes        | The provided CVC code was incorrect                                                                                    | Ask the customer to re-enter the correct CVC                                                                               |
| `INCORRECT_NUMBER`                 | Soft | Yes        | The card number was entered incorrectly                                                                                | Ask the customer to re-enter the correct card number                                                                       |
| `INSUFFICIENT_FUNDS`               | Soft | Yes        | The account has insufficient funds to complete the transaction                                                         | Ask the customer to use another payment method or retry once funds are available                                           |
| `INVALID_ACCOUNT`                  | Hard | Yes        | The account details provided are invalid                                                                               | Ask the customer to contact their bank or use another card                                                                 |
| `INVALID_AMOUNT`                   | Soft | Yes        | The transaction amount is invalid                                                                                      | Verify the amount and any purchase limits with the customer                                                                |
| `INVALID_CARD_NUMBER`              | Soft | Yes        | The card number format is invalid                                                                                      | Ask the customer to re-enter a valid card number                                                                           |
| `INVALID_CARD_OWNER`               | Soft | Yes        | The card owner information is invalid                                                                                  | Ask the customer to correct the cardholder name                                                                            |
| `INVALID_CVC`                      | Soft | Yes        | The CVC format is invalid                                                                                              | Ask the customer to re-enter a valid CVC                                                                                   |
| `INVALID_EXPIRY_YEAR`              | Soft | Yes        | The card expiry year is invalid                                                                                        | Ask the customer to enter a valid expiry date                                                                              |
| `INVALID_PIN`                      | Soft | Yes        | The provided PIN is incorrect                                                                                          | Ask the customer to re-enter the correct PIN                                                                               |
| `INVALID_REQUEST`                  | Soft | Yes        | The transaction request contains invalid data                                                                          | Check the payment request fields and resubmit with valid data                                                              |
| `INVALID_UPI_ID`                   | Soft | Yes        | The UPI ID provided is invalid                                                                                         | Ask the customer to enter a valid UPI ID                                                                                   |
| `LIMIT_EXCEEDED`                   | Soft | Yes        | The transaction exceeds the card or account limit                                                                      | Ask the customer to contact their bank about limits, or use another method                                                 |
| `LIVE_MODE_TEST_CARD`              | Hard | Yes        | A test card was used in live mode                                                                                      | Use a real card — retrying the test card will always fail in live mode                                                     |
| `LOST_CARD`                        | Hard | Yes        | The card has been reported as lost                                                                                     | Show the customer a generic decline message — do not reveal the reason. Ask them to use another card                       |
| `MANDATE_INVALID`                  | Soft | Yes        | The payment mandate is invalid                                                                                         | Ask the customer to set up the payment mandate again                                                                       |
| `MANDATE_REQUIRED`                 | Soft | Yes        | A mandate is required for this transaction                                                                             | Set up a mandate and ask the customer to authorize it before charging                                                      |
| `MANDATE_REQUIRED_SYSTEM`          | Hard | No         | The system requires a mandate for this transaction type                                                                | Ensure the mandate setup flow is completed before charging                                                                 |
| `NETWORK_ERROR`                    | Soft | No         | A network error occurred during the transaction                                                                        | Transient — retry the payment after a short delay                                                                          |
| `NETWORK_TIMEOUT`                  | Soft | No         | The network request timed out                                                                                          | Transient — retry the payment after a short delay                                                                          |
| `ORDER_ALREADY_EXISTS`             | Soft | No         | An order already exists for this transaction (duplicate order creation)                                                | Check the status of the existing order before retrying; contact support if it persists                                     |
| `ORDER_CREATION_FAILED`            | Soft | No         | Failed to create the order for the transaction                                                                         | Transient/system error — retry the payment; contact support if it persists                                                 |
| `PAYMENT_METHOD_PROVIDER_DECLINED` | Hard | Yes        | The payment method provider declined the transaction                                                                   | Ask the customer to contact their provider or use another payment method                                                   |
| `PAYMENT_METHOD_UNSUPPORTED`       | Hard | Yes        | The payment method is not supported for this transaction                                                               | Ask the customer to use a supported payment method                                                                         |
| `PICKUP_CARD`                      | Hard | Yes        | The card has been reported as lost or stolen and flagged for pickup                                                    | Show the customer a generic decline message — do not reveal the reason. Ask them to use another card                       |
| `PROCESSING_ERROR`                 | Soft | No         | An error occurred while processing the transaction                                                                     | Transient — retry the payment; if it persists, ask the customer to contact their bank                                      |
| `PROVIDER_UNSUPPORTED`             | Hard | No         | The payment provider does not support this transaction type                                                            | Ask the customer to use another payment method                                                                             |
| `REENTER_TRANSACTION`              | Soft | Yes        | The transaction needs to be re-entered                                                                                 | Ask the customer to retry the payment                                                                                      |
| `REVOCATION_OF_AUTHORIZATION`      | Hard | Yes        | The authorization for the transaction was revoked                                                                      | Ask the customer to use another payment method                                                                             |
| `STOLEN_CARD`                      | Hard | Yes        | The card has been reported as stolen                                                                                   | Show the customer a generic decline message — do not reveal the reason. Ask them to use another card                       |
| `SUBSCRIPTION_NOT_ACTIVE`          | Hard | No         | The subscription is not active, so the recurring charge could not be processed                                         | Reactivate the subscription (for example, by updating the payment method) before attempting the charge again               |
| `TRANSACTION_NOT_ALLOWED`          | Hard | Yes        | The transaction is not allowed for this card or account                                                                | Ask the customer to contact their bank to allow this transaction type, or use another card                                 |
| `TRANSACTION_NOT_APPROVED`         | Hard | Yes        | The transaction was not approved                                                                                       | Ask the customer to contact their bank or try another card                                                                 |
| `TRY_AGAIN_LATER`                  | Soft | No         | The transaction should be retried later                                                                                | Transient — retry the payment later                                                                                        |
| `UNKNOWN_ERROR`                    | Soft | No         | An unknown error occurred                                                                                              | Retry the payment; if it persists, contact support                                                                         |

<Note>
  **User Error** indicates whether the payment decline can be resolved by the customer. When `Yes`, the customer can take action to fix the issue (for example, entering correct card details). When `No`, the decline is due to system-level issues or bank restrictions that the customer cannot resolve directly.
</Note>

カードは、発行銀行のリスクエンジンがカード所有者をハイリスク顧客としてフラグ付けした場合にも却下されることがあります。このような拒否には、一般的なコードが表示されることがあり、たとえば`DO_NOT_HONOR`、`GENERIC_DECLINE`、`CARD_DECLINED`、`TRANSACTION_NOT_APPROVED`、または`FRAUDULENT`などがあります。この場合、銀行は特定の理由を共有しないため、Dodo Paymentsも販売者も決定を覆すことはできません。顧客に銀行へ連絡してフラグを解決するよう依頼するか、別のカードや支払い方法を使用するように促してください。

## プログラムによる失敗の処理

`error_code`を`payment.failed` webhookまたは支払いオブジェクトから読み取り、上記の推奨アクションにマップし、再試行するかどうかを判断します。サブスクリプションの更新の場合、ソフト拒否は自動的に再試行されます — [サブスクリプション支払いの再試行](/features/recovery/payment-retries)を参照してください。

カード拒否でないAPIレベルおよびビジネスロジックエラー（例：`PAYMENT_NOT_SUCCEEDED`または`REFUND_WINDOW_EXPIRED`）については、[エラーコード](/api-reference/error-codes)リファレンスを参照してください。

## 関連

失敗した支払いの検出、表示、再試行に関するエンドツーエンドガイド。

非拒否エラーのAPIおよびビジネスロジックエラーコード。

サブスクリプションの更新でソフト拒否を回復する自動再試行。

支払い方法の更新を促すことでハード拒否を回復するメールシーケンス。

## サポート

取引の失敗や統合の問題についての追加のヘルプが必要な場合は、[support@dodopayments.com](mailto:support@dodopayments.com)まで弊社のサポートチームにお問い合わせください。