Stripe · Decline codes
What does the Stripe card_declined error mean?
Checked
The Stripe error code card_declined means the card has been declined. It is the umbrella error for every card refusal: Stripe adds a decline_code attribute that gives the reason, such as insufficient_funds or do_not_honor. When no decline_code comes back, the bank gave no reason. The shopper should try another card or contact their bank; the store should read the decline_code before deciding on a retry.
- Type
- Error code that wraps every card decline
- Who declined
- Usually the card's bank; see decline_code
- Retry
- Depends on the decline_code
- Shopper action
- Try another card or contact the bank
- Merchant action
- Look up the decline_code to see the real reason
- PlatformDTC renewal
- With no decline_code: one retry 48–72 hours later (Smart retry)
What PlatformDTC does
When only card_declined comes back, PlatformDTC's checkout adds "Your card was declined. Try another card or contact your bank." and, if the store has PayPal card payments as its backup, offers a second try there. With Smart retry on, a renewal with card_declined and no decline_code is retried once, 48–72 hours later; a second refusal asks the customer for a new payment method.
Why it happens
Any time a card payment is refused, Stripe returns card_declined. The specific reason travels separately in the decline_code, which can be anything from a wrong CVC to a lost card.
If no decline_code is present, the bank refused without giving a reason.
What the shopper can do
Check the card details, then try again or use another card. If the card keeps failing, call your bank: banks explain declines only to the cardholder.
What the store can do
Show a clear message and alternative payment methods. In reports, group failures by decline_code rather than by card_declined, or every failure will look the same.
For developers
error.code = card_declined; the reason is in error.decline_code (also last_payment_error.decline_code on the PaymentIntent). Also read charge.outcome.advice_code and network_decline_code. Storing only card_declined loses the information needed to choose between a retry, an update-card request and a stop.
Frequently asked questions
- What is the difference between card_declined and a decline code?
- card_declined is the error code for any card refusal. The decline code, in the decline_code attribute, explains why.
- Should I retry a card_declined error?
- Look at the decline_code first. Some reasons clear with time, others mean the card will never work. Without a decline_code, one spaced retry is reasonable.
Sources
- Error codes — Stripe
- Stripe decline codes — Stripe
- Card declines — Stripe
Related
- generic_decline — Declined for an unknown reason, or blocked by Stripe Radar or Adaptive Acceptance.
- do_not_honor — The bank declined the card without saying why.
- insufficient_funds — The card doesn't have enough money or credit for this payment.
- call_issuer — The bank declined without a reason and wants the cardholder to contact it.
- payment_intent_authentication_failure — The card failed the bank's authentication check (such as 3-D Secure).
- authentication_required — The bank wants the cardholder to verify the payment, usually with 3D Secure.
- authentication_not_handled — Verification was required, the shopper skipped it, and the bank declined again.
- approve_with_id — The bank could not authorize the payment as sent; one more try may work.