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:

  1. Should I retry this card?
  2. Who can actually fix it? The bank, the customer, or me?
  3. 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.