Passer au contenu principal

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

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. For subscription renewals, Dodo Payments applies this distinction automatically: soft declines are re-attempted by Subscription Payment Retries, while hard declines end the retry chain immediately and are best handled with Subscription Dunning.
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.

​
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.
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.
A card can also be declined when the issuing bank’s own risk engine flags the cardholder as a high-risk customer — independent of the merchant or the transaction details. These declines typically surface as generic codes such as DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED, or FRAUDULENT. In these cases the bank does not share the specific reason, and neither Dodo Payments nor the merchant can override the decision. Ask the customer to contact their bank to resolve the flag, or use a different card or payment method.

​
Handling Failures Programmatically

Read error_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.

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.

​
Support

For additional help with transaction failures or integration issues, please contact our support team at support@dodopayments.com.
Dernière modification le 9 juillet 2026