Stripe decline codes and error codes
Stripe returns two different things when a card fails, and confusing them is the most common reason a lookup comes up empty. The error's code attribute says what kind of failure it was — card_declined for a card the issuer refused. The decline_code attribute on that same error says why the issuer refused it. A value like do_not_honor is a decline code and will never appear as an error code.
Checked against Stripe’s own documentation.
- card_declined
card_declined
The card was declined by the issuer. `card_declined` is an error code, not a decline code — the reason for the decline is in the `decline_code` attribute on the same error, and that is the value you actually need to look up.
- do_not_honor
do_not_honor
Stripe's wording is exact and deliberately unhelpful: "The card was declined for an unknown reason." The issuer refused the payment and disclosed nothing about why, and Stripe cannot tell you more than the issuer told it.
- generic_decline
generic_decline
Stripe documents this as: the card was declined for an unknown reason, or Stripe Radar or Adaptive Acceptance blocked the payment. Unlike `do_not_honor`, this one can mean the payment never reached the issuer at all.
- insufficient_funds
insufficient_funds
Stripe's wording: "The card has insufficient funds to complete the purchase." The card is valid and the account is in good standing — there is simply not enough available balance or credit.
- expired_card
expired_card
Stripe's wording: "The card has expired." The documented next step is short — the customer needs to use another card. No retry of the same details will succeed.
- incorrect_cvc
incorrect_cvc
Stripe's wording: "The CVC number is incorrect." The customer needs to try again using the correct CVC. There is a separate `invalid_cvc` with the same description — the difference is whether the value was wrong or malformed.
- processing_error
processing_error
Stripe's wording: "An error occurred while processing the card." The documented next step is to attempt the payment again, and if it still cannot be processed, to try again later. One of the genuinely transient codes.
- issuer_not_available
issuer_not_available
Stripe's wording: "The card issuer couldn't be reached, so the payment couldn't be authorised." Attempt the payment again; if it still fails, the customer needs to contact their card issuer.
- fraudulent
fraudulent
Stripe's wording: "The payment was declined because Stripe suspects that it's fraudulent." Stripe is explicit about how to handle it — do not report more detailed information to your customer; present it the same way as a generic decline.
- lost_card
lost_card
Stripe's wording: "The payment was declined because the card has been reported as lost." The specific reason should not be reported to the customer — present it as a generic decline.
- stolen_card
stolen_card
Stripe's wording: "The payment was declined because the card is reported stolen." As with a lost card, do not report the detail to your customer — present it in the same manner as a generic decline.
- card_velocity_exceeded
card_velocity_exceeded
Stripe's wording: "The customer has exceeded the balance, credit limit, or transaction amount limit available on their card." The customer needs to contact their card issuer for more information.
- authentication_required
authentication_required
The card was declined because the transaction requires authentication such as 3-D Secure. It is not a refusal of the payment — it is a request for the cardholder to prove who they are, and the payment can usually still complete.
- testmode_decline
testmode_decline
Stripe's wording: "A Stripe test card number was used." A genuine card must be used to make a payment. This means a test card reached live mode — nothing is broken with the card or the issuer.