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, thepayment.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—0for the original charge,1or higher for each scheduled subscription renewal retry.
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.
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 |
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 |
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.Handling Failures Programmatically
Readerror_code from the payment.failed webhook or the payment object, map it to the recommended action above, and decide whether to retry. For subscription renewals, soft declines are retried for you automatically — see Subscription Payment Retries.
For API-level and business-logic errors (such as PAYMENT_NOT_SUCCEEDED or REFUND_WINDOW_EXPIRED) that are not card declines, see the Error Codes reference.
Related
Handle Payment Failures
End-to-end guide to detecting, surfacing, and retrying failed payments.
Error Codes
API and business-logic error codes for non-decline failures.
Subscription Payment Retries
Automatic retries that recover soft declines on subscription renewals.
Subscription Dunning
Email sequences that recover hard declines by prompting a payment method update.