Stripe failed payment reasons: every decline code, what it means, and what to do about each

Stripe's documentation lists decline codes alphabetically with a one-line description each. That is the right reference for a developer handling the invoice.payment_failedevent. It is the wrong shape for the question a finance lead or a CS manager actually has, which is: this customer's payment failed, do we retry it, do we email them, and what do we say?

This page answers that question, code by code, using the classification Exeechain applies to every failed invoice it reads from Stripe. Two things to know before the table. First, the classis what matters; the individual code is only how you find the class. Second, the most important decision is not “retry or not”. It is “is an automated email appropriate at all”, and for eight of the codes the answer is no.

Where to find the code

On a failed subscription payment, Stripe fires invoice.payment_failed. The invoice's latest charge (or payment intent) carries failure_code, failure_message, and inside outcome a decline_code such as insufficient_funds. The decline code is the bank's answer; the failure message is Stripe's paraphrase. Use the code. In the Dashboard it is shown on the payment's detail page under the decline reason.

If there is no code, which happens when the failure reached you through an events feed with no invoice behind it, treat it as unknown. The unknown class exists so that a system with no evidence cannot send the confident version of anything.

The five classes

Unknown: no code at all

Some failures arrive with no decline code: the invoice ledger was never loaded, or the failure came through an events feed as a boolean. The temptation is to assume the benign case and send the “your card probably expired” email. Do not. The neutral message claims no reason, offers both routes (retry, or a different card if it keeps failing), and asserts neither. A customer told to replace a card that works stops believing the emails.

On timing the retry

For the retriable and bank-refused classes, when you retry matters more than how often. Balances refill on paydays, and the 1st and 15th are when most do. So the retry, or the reminder that gets the customer to pay it themselves, should land on the next 1st or 15th that is at least 24 hours out, so a failure on the 14th does not trigger an attempt the customer has had no chance to fund. This is a heuristic and should be labelled as one wherever it shows up; whether it beats a fixed interval on a given book is something to measure with a holdout, not assume.

One constraint worth stating plainly: if your recovery tool reads Stripe read-only, it does not reschedule Stripe's own retries. The retry schedule belongs to your Stripe Billing settings. What the tool can time is its outreach, the nudge that gets the customer to settle the invoice through a pay link. A product that claims to be retrying cards it cannot retry is describing work it does not do.

What happens to the subscription

Stripe decides. Smart Retries re-attempts the charge on its schedule, and the subscription settings decide whether a subscription that stays unpaid is cancelled, paused, or left unpaid. Because that date lives in Stripe, any dunning email sent from another tool should not state a cancellation date it does not control. The five-touch dunning sequence says access will stop; it never says when.

Frequently asked questions

Where this comes from

The classification is the one Exeechain applies to every failed invoice it reads from Stripe, and it decides three things for each one: whether an automated email may go out, which of three copy variants it uses, and when it lands. Codes are Stripe's own decline_code values; anything absent from the table falls through to unknown and is treated conservatively. The failed payment recovery page shows what the sequence looks like on a real book.