Stripe Card Decline Codes: What to Tell the Customer for Each One
Short answer: When Stripe declines a card it returns an error with a code, and the code decides what you should say. Some declines are the customer's to fix, such as an expired card or wrong security code. Others come from the issuing bank and give you little detail, with do_not_honor and generic_decline being the best known. Never tell a customer why their bank said no, because you usually do not know. Show a short, neutral message, offer another way to pay, and keep the code in your own records. As of November 2026 the full list lives in Stripe's decline documentation, and it is the authority for exact meanings.
Why vague messages are deliberate
Banks often withhold the reason for a decline so fraudsters cannot learn what works. Stripe passes on what it gets. That is why a generic decline gives you almost nothing. Your job is to be helpful without guessing, and without revealing anything that would help a card tester.
Two places hold the information:
- The Dashboard payment page, which shows the decline code and a plain explanation for you.
- The API error, which carries code and decline_code fields that your site or app can read.
The customer should see a friendlier message than either one.
Decision table: code, meaning, customer wording and action
| Code | What it generally means | Say to the customer | Retry? |
|---|---|---|---|
| insufficient_funds | Not enough available balance or credit | That card could not be used for this amount. Please try another card or payment method. | Let them try another card |
| expired_card | Card past its expiry date | Please check the expiry date or use a different card. | After they correct it |
| incorrect_cvc | Security code wrong | Please re-enter the three or four digit code on your card. | After correction |
| incorrect_number or invalid_number | Card number mistyped | Please check the card number. | After correction |
| card_declined with generic_decline | The bank declined without a reason | We could not process this card. Please try another, or contact your bank. | Not automatically |
| do_not_honor | Bank refused, reason withheld | Same as above | Not automatically |
| lost_card or stolen_card | Card reported as lost or stolen | Treat it as a generic decline in what you say. Do not mention loss or theft. | No |
| fraudulent | Flagged as risky by the bank or Stripe | We could not process this payment. Please try another method. | No |
| authentication_required | Bank wants 3D Secure | Your bank needs to confirm this payment. Please complete the verification step. | Yes, with the verification step |
| processing_error | Temporary problem | Something went wrong while processing. Please try again in a minute. | Yes, once or twice |
| try_again_later | Issuer asked to retry later | Please try again shortly. | Yes, later |
Use the table as a starting point, then compare with the current official list before you encode it into your website.
Writing the customer-facing message
Keep these principles:
- Do not blame. Avoid your card was refused for suspicious activity. You do not know.
- Give a next step. Another card, a different method such as a wallet or bank transfer, or a phone number.
- Keep the field data. Do not clear the form; let the customer correct one field.
- Use the same wording for the dangerous ones. Lost, stolen and fraudulent all deserve the same generic reply, so a thief learns nothing.
- Avoid revealing which of several attempts failed. If the same card has been tried many times, slow down the form instead.
Step by step: handle a decline in your own checkout
- Read the error code from the response, not the message text.
- Map it to one of three buckets: fix input, try another method, try later.
- Display the matching message from your table.
- Log the code, the amount, time and an order or session ID in your own system.
- After three failed attempts in a short window, pause the form for a few minutes. This protects against card testing.
- If you use Stripe Checkout or the Payment Element, much of this is handled for you, so confirm what the hosted form already says before adding your own.
Support scenario, labelled illustrative
A customer emails a fictional garden centre saying that "my card works everywhere else". The owner finds a generic_decline in the Dashboard. A good reply says the payment did not go through, that the shop cannot see the bank's reason, and suggests contacting the card issuer or using another method. A weak reply says your card is blocked, which may be untrue and could be alarming.
Recurring payments and retries
For subscriptions, Stripe has smart retry and email options, found in billing settings. Retrying a stolen_card decline is pointless, whereas retrying a processing_error can succeed. For failed recurring payments, send a link to update the card, not just a notice that a payment failed.
Mistakes to avoid
- Telling customers their card was reported lost.
- Retrying a hard decline automatically, which can annoy the bank and raise your dispute and risk numbers.
- Showing raw error text from the API, which can contain technical detail.
- Treating all declines as fraud, and blocking genuine buyers.
- Ignoring patterns. Many declines on small amounts from different cards is a sign of card testing. Look at Radar rules and rate limits.
FAQ
Why does one customer card fail on this site but work elsewhere?
Each bank scores a payment on its own rules, including merchant type, country, amount and past behaviour. Your site is simply one input.
Should I ask for a different card by phone?
Yes, but never accept card numbers by email or chat. Send a payment link instead.
Can I find out the real reason?
Usually only the customer can, by calling their bank.
Does a decline cost me anything?
Stripe's pricing page lists current fees, so confirm failed-payment charges, if any, there.
If your payment flow needs friendlier error handling or recovery emails, get in touch with us and describe your current checkout.