Decline guide · card_declined
Stripe card_declined: what it means and how to fix it.
card_declined is the error Stripe returns when a card payment is refused. On its own it doesn't say why. The reason sits in a second field, the decline code: insufficient_funds, expired_card, do_not_honor and so on. Read that first, because the fix depends on it.
card_declined is the envelope.
The letter inside is the decline code. Here's where to read it.
| Where you look | What to read |
|---|---|
| Stripe DashboardPayments, then the failed payment | Open the payment. Stripe shows why it failed and whether the card issuer declined it or it was blocked before it reached the bank. |
| Your code or logsThe API error | The error's code is card_declined; its decline_code holds the reason. Log both, not just the first. |
| Payments exportA CSV from the Dashboard | Failed payments carry their decline reason, so you can count which codes cost you most. The free check does that count in your browser. |
If the decline code is generic_decline, the bank gave no reason at all. That has its own guide.
Fix it by the code, not the error.
Three steps that hold for any card_declined.
- Look up the decline code in the table below and follow that fix. Money short, card out of date and a bank block each need a different message.
- Tell the customer plainly that the payment didn't go through, and offer another card or another payment method you already accept in Stripe.
- For subscriptions, send a short "update your card" email with a link to your billing page, instead of waiting for automatic retries to fail.
If the code points to fraud (fraudulent, lost_card, stolen_card), Stripe's docs advise showing the customer a general "card declined" message, not the real reason.
ActionHi ‹first name›,
We tried to take the payment for ‹order or plan›, but the card was declined.
You can try again, or use another card, here: ‹payment link›. If it keeps happening, your bank can tell you why.
Thanks,
‹your name›
Want to see how often it happens to you? Run the free check on your Stripe payments export →
Recover lost revenue.
The Failed-Payment Recovery Kit: a download on Whop, yours right after paying. No subscription, no account with us.
- Dunning email templates to send after a failed payment
- A Stripe settings checklist
- A recovery playbook
One-time purchase · Files, not software