A field guide to Stripe decline codes, and what to actually do about each

#payments #webdev #stripe #productivity

TL;DR: Stripe tells you why a card failed. Most checkouts hide it. Here is the decode, mapped to the fix, so you stop guessing.

Every failed card payment comes with a reason from Stripe. The problem is most checkouts swallow it and show you "your card was declined." If you can see the actual decline_code (your dashboard, the API response, or support), the fix is usually obvious. Here is the cheat sheet I wish I had.

Disclosure: I work on Fizen, a payments product. No pitch here, this is the reference I use myself.

The ones you will actually hit

insufficient_funds. The honest one. Top up or use another card.
incorrect_zip / incorrect_cvc. AVS or CVC mismatch. Match the billing details to your bank exactly. Very common for non-US cards.
card_not_supported. The card type or country is not accepted for this purchase. Use a card from a supported region.
currency_not_supported. The card cannot do this currency. Same fix, different card.
do_not_honor. The vaguest one. The bank said no without saying why. Call the bank or try another card. Usually a risk flag.
generic_decline. No reason shared by the bank. Treat like do_not_honor.
transaction_not_allowed. The bank blocks this category or online use. Toggle international and online payments in your bank app.
fraudulent / lost_card / stolen_card. The bank flagged risk. Do not retry, contact the bank.
expired_card. Self-explanatory.
processing_error. Transient on Stripe or the bank side. Wait and retry once.
testmode_decline. You used a test card on a live key. Switch keys.

How to read them in practice

Soft declines (do_not_honor, generic_decline, processing_error) sometimes clear on retry or with a different card. Retrying a hard decline like stolen_card just digs the hole deeper.
AVS and CVC declines are on you and fixable in seconds. Most cross-border failures are one of these.
A code that says "country" or "not supported" is a policy or region problem, not a money problem. A different card from a supported region is the only fix.

Bookmark this for the next time a checkout just says "declined." If a code is missing here, add it in the comments and I will fold it in.

If your declines are specifically cross-border on USD tools, I wrote up the card side of it here.