Skip to content

Card Decline by FlowMRR · Free Stripe decline_code lookup for SaaS

Understand any Stripe decline code and know what to do next.

Paste a decline code or error message. Get the plain-English meaning, who can fix it, whether a retry will help, and a ready-to-send customer email template.

We look for a known code, or one of Stripe's standard messages such as "Your card was declined.", anywhere in what you paste.

Try:

Browse all 51 codes by category

  • No Stripe key needed
  • No signup
  • Email template included

Free · instant results · no Stripe key, no signup.

Look up a Stripe decline code

Stripe decline codes by category

Grouped by what to do about them. Every code links to its own page.

51 codes

Which customers to contact first, and with what message?

FlowMRR reads your failed payments from Stripe, scores who to contact first and drafts the recovery email with the right tone for each decline code. You review it and send it yourself.

Try FlowMRR free

The same rules, in your own code

Everything this page knows is an open-source npm package, stripe-declines: the 51 codes with their category, retry verdict, who can fix them, a message to show the customer and an email to send, in English and French. It reads a code, Stripe's error message, a Charge or a webhook payload, and ships as ESM, CommonJS, TypeScript types and a command line. MIT licence, no dependencies.

npm install stripe-declines

In your code

import { explain } from "stripe-declines";

explain("do_not_honor"); // { retry: "likely", fixer: "bank", ... }

Package on npmSource on GitHub

To decide which declined accounts to follow up first, see how FlowMRR helps you recover failed Stripe payments.

How to handle a Stripe card decline

A decline is the issuing bank, Stripe or the card network refusing a payment. Stripe reports it as a card_declined error with a decline_code that says why, as far as the bank was willing to say. What you do next depends on that code, on the advice Stripe attaches to the attempt, and on who blocked the payment.

What a decline code is

When a card payment fails, Stripe returns an error whose code is card_declined and whose decline_code carries the reason, for example insufficient_funds or expired_card. On a PaymentIntent it is last_payment_error.decline_code; on a Charge it is outcome.reason; on a failed subscription invoice the same fields sit on the invoice's payment attempt. The code comes from the issuer's response, translated by the network. Many issuers answer with do_not_honor or generic_decline, which say nothing more than "no"; Stripe's reference documents those as a decline for an unknown reason, and only the customer's bank can say more.

Soft and hard declines

A soft decline is a refusal that can clear on its own: a temporary hold, a limit hit that day, an issuer that was unreachable. Retrying the same card later can succeed, and Stripe's Smart Retries exist for this case. A hard decline will not clear until something changes: the card expired, the number is wrong, the account was closed, the bank asked you to stop. Retrying as is cannot work, and the card networks limit reattempts after certain responses, with fees for merchants who go over. This page labels each code as one or the other, but Stripe publishes no official soft or hard list, so treat the label as a default rather than a rule.

advice_code overrides the code

When the issuer gives one, Stripe adds an advice_code to the error and to the Charge's outcome. It has three values: do_not_try_again, try_again_later and confirm_card_data. It is Stripe's verdict for that attempt, so it takes precedence over the general rule for the code. A do_not_honor with try_again_later is a soft decline; a do_not_honor with do_not_try_again is a hard one, whatever the table says. confirm_card_data means the details the customer typed are wrong or stale, and a retry with the same details will fail. The lookup above reads the advice_code from a pasted payload and changes its verdict accordingly.

Radar blocks arrive as card_declined

Not every refusal comes from the bank. When Stripe Radar blocks a payment, the Charge still fails with failure_code card_declined, but its outcome.type is blocked and outcome.reason is highest_risk_level (Radar's own score) or rule (one of your rules). The bank was never asked. Retrying sends the same payment to the same rules and fails the same way, so a Radar block must not be retried: review the payment in Stripe, adjust the rule if it was wrong, or let the customer try with another method. Blocks by Adaptive Acceptance show as generic_decline with outcome.reason low_probability_of_authorization.

Lost, stolen and fraudulent cards

lost_card, stolen_card, pickup_card and fraudulent mean the bank flagged the card, not the customer. Stripe asks merchants to show these to the customer as a generic decline, with no mention of the reason, for two reasons: the person paying may be the cardholder with a card that was reported in error, and if they are not, revealing what was detected would help a fraudster. The customer messages on this page follow that rule. Internally, treat them as hard declines: stop retrying, ask for another card, and keep the real code for your own records.

Stripe decline codes, explained

Related guides

Where do I find the decline code in Stripe?

On the failed payment in the Stripe dashboard, under the payment details, or in the API as `last_payment_error.decline_code` on the PaymentIntent, or `outcome.reason` on the Charge. `card_declined` is the generic error code; the actual reason is in `decline_code`.

Should I retry a declined payment?

It depends on the code. Temporary refusals (generic_decline, do_not_honor, insufficient_funds, try_again_later) often succeed on a later attempt, such as one scheduled by Stripe's Smart Retries. Dead or blocked cards (expired_card, lost_card, stolen_card, fraudulent) never recover by retrying; only a new card helps. Authentication codes need the customer to confirm the payment themselves.

Does retrying hard declines hurt?

Yes, and it can cost you directly. Visa and Mastercard both have rules on reattempting declined payments: when the issuer signals the payment will never be approved (lost or stolen card, closed account, do-not-try-again responses), retrying at all breaks the rules, and other declines are capped at a set number of reattempts over a rolling period. Merchants who go over can be charged fees by the network on each excess attempt, on top of a lower authorization rate. Stop after a hard decline and ask for another card.

Why can do_not_honor succeed later if the bank said no?

It is a catch-all answer from issuers: a temporary lock, a velocity rule, a risk score at that moment. When the cause was temporary, an attempt a few days later can go through, though nothing guarantees it. That is why it is classified as a temporary refusal here.

Is this tool connected to my Stripe account?

No. It is a static reference built from Stripe's documented decline codes and from what we see across FlowMRR accounts. The search runs in your browser and is unlimited. The code you looked up may be recorded to measure usage, but not the raw text you paste.

Can I use these rules in my own application?

Yes. The data and the lookup behind this page are published as the open-source npm package stripe-declines (MIT), the same code this page runs. `npm install stripe-declines`, then `explain("do_not_honor")` or `customerMessage(error.decline_code, "fr")` give you the verdict, the action and the customer wording; a `stripe-declines` command does the same from a terminal. Corrections are welcome on GitHub, with the Stripe documentation that backs them.

Contact us
FlowMRR

Let's talk

A question, a technical issue or an idea for a partnership? Write to the FlowMRR team.