Decline codes
Use decline codes to route recovery logic, not just retry blindly
A practical decision tree for the most common Stripe decline codes and the right action for each failure type.
Recommended action
Soft decline due to temporary account balance issues. Best handled with a gentle retry and reminder flow.
Retry automatically, send a friendly email, and provide an update payment link.
Recommended action
Hard decline from an expired card. Stop retries and ask the customer to update payment details.
Send clear instructions and a direct Stripe Customer Portal link immediately.
Recommended action
Fraud-related decline that requires immediate customer attention.
Pause retries, notify the customer, and prompt payment method update through a secure link.
Recommended action
A temporary processor issue that may resolve quickly. Reattempt later and alert the ops team.
Retry on a delayed schedule and surface the issue to monitoring dashboards.
Recommended action
Generic decline that needs more context. Use follow-up messaging and collect additional payment data.
Route to a diagnostic email, ask for updated card details, and retry once after customer action.
How to use this decision tree
The key to higher recovery is pairing Stripe decline codes with behavior. Soft declines like insufficient funds should be retried and reminded. Hard declines like expired or stolen cards should skip retries and prompt customers to update payment details.