If you run a subscription business on Stripe, you've seen this in your logs:
{ "code": "card_declined", "decline_code": "do_not_honor", "message": "Your card was declined." } And then you have to decide three things:
- Should I retry this card?
- Who can actually fix it? The bank, the customer, or me?
- What do I tell the customer?
Stripe's decline code reference lists the codes and a one-line next step for each. What it doesn't give you is a hard/soft split you can code against, or customer-facing copy that's safe to show. So every team ends up writing its own switch (decline_code), usually with a few wrong branches.
We wrote ours while building failed-payment recovery for FlowMRR, then pulled it out into a small MIT package: stripe-declines.
npm install stripe-declines No dependencies, ESM and CommonJS, TypeScript types, Node 18+.
One call, three answers
import { explain } from "stripe-declines"; const d = explain("do_not_honor"); d.retry; // "likely" (likely | maybe | no) d.fixer; // "bank" (bank | customer | you) d.action; // "Retry on Stripe's schedule. Suggest the customer calls their bank if it fails twice." d.customer; // "Your bank declined this payment. This is often temporary: ..." d.email; // a full email with {name}, {product}, {link}, {company} All 51 codes are grouped into eight categories, and each category has a different playbook:
| Category | What happened | Retry the same card? | Who fixes it |
|---|---|---|---|
| soft | Bank refused, no lasting reason | Often succeeds later | Bank |
| funds | Not enough balance or credit | Often, a few days later | Customer |
| card | Card is dead or wrong | No | Customer |
| limit | A card limit was hit | No, until it changes | Customer |
| restricted | Card can't be used for this payment | No | Customer |
| auth | Bank wants 3DS / SCA | Once they authenticate | Customer |
| fraud | Issuer blocked the card | Never | Customer |
| merchant | Something on your side | Once you fix it | You |
It reads whatever you paste
In practice you rarely have a clean code. You have an error object, a Charge, a webhook payload, or a log line someone pasted into Slack. explain() takes any of them:
explain("Your card has insufficient funds.")?.code; // "insufficient_funds" explain("Votre carte a des fonds insuffisants.", "fr")?.code; // "insufficient_funds" explain("{ code: 'card_declined', decline_code: 'incorrect_cvc' }")?.code; // Node dump explain("{'decline_code': 'expired_card'}")?.code; // Python dump explain("hello"); // null JSON, and objects as dumped by Node, Python, PHP or Ruby all work. Missing or non-string input returns null instead of throwing, so this is safe at checkout:
import { customerMessage } from "stripe-declines"; const message = customerMessage(error.decline_code ?? error.code, locale) ?? genericMessage; The three traps
These are the cases where most hand-written dunning logic gives the wrong advice.
1. advice_code beats the decline code
On many declines, Stripe now sends an advice_code: do_not_try_again, try_again_later or confirm_card_data. When it's there, it should decide the retry, whatever the decline code says.
explain('{"decline_code":"do_not_honor","advice_code":"do_not_try_again"}'); // { code: "do_not_honor", retry: "no", retrySource: "advice_code", ... } A plain do_not_honor is usually worth a later retry. A do_not_honor with do_not_try_again is not.
2. A Radar block looks like a decline, but isn't one
When Radar blocks a payment, the charge still says failure_code: "card_declined". If you map that to "soft decline, retry later", you'll keep hammering a payment Stripe already decided not to send to the bank.
import { findCode, findNote } from "stripe-declines"; const charge = '{"failure_code":"card_declined","outcome":{"reason":"highest_risk_level","type":"blocked"}}'; findCode(charge); // null, not a bank decline findNote(charge)?.term; // "highest_risk_level" 3. Never tell the customer their card was reported stolen
For lost_card, stolen_card, pickup_card and fraudulent, Stripe asks you to present the failure like a generic decline. You don't have to stay silent, though: asking for another card is fine, and it still recovers real customers who were flagged by mistake.
customerMessage("stolen_card"); // "Your card was declined. Please pay with another card, or contact your bank for details." The package's tests enforce this: no customer message or email names the real reason for those codes, and none promises a retry that the code's verdict says won't happen.
From the terminal
npx stripe-declines do_not_honor npx stripe-declines insufficient_funds --customer npx stripe-declines "Your card has insufficient funds." --lang fr --email # explain declines as they happen stripe logs tail | grep decline_code | npx stripe-declines --json Not using JavaScript?
The data ships as plain JSON, so any language can read it:
import codes from "stripe-declines/codes.json"; It holds the eight categories, the 51 codes (50 decline codes plus card_declined, which people paste all the time), four notes for Radar and Adaptive Acceptance blocks, and a reviewed date for the last check against Stripe's reference.
Just want to look up a code?
There's a free web version of the same rules, no signup and no Stripe key: the Card Decline Decoder. Paste a code or a whole error and you get the meaning, the retry verdict and a customer email.
Contributions welcome
Decline handling is full of folklore. If you think a verdict is wrong, open an issue with the Stripe documentation that backs it: github.com/flowmrr/stripe-declines.
How do you handle declines today: a hand-written map, Smart Retries only, or a dunning tool? I'm curious which codes cause you the most trouble.
![Physical AI Engineering — Ch.13: Computing Platforms for Physical AI [EN]](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fg3ou3b2eumf1epqj4bk4.png)

![Physical AI Engineering — Ch.04: Localization Mapping and World Understanding [EN]](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fuscy0mautxl2mb4834vd.png)