Stripe decline codes: meanings and solutions
Failed charges in Stripe return specific decline codes. They're split into soft declines and hard declines. Here's what every code means and what to do about it.
Soft vs. hard declines
Declines are split into two categories.
Temporary. The card still works.
The charge failed this time, for example because of low funds. A retry later can succeed.
insufficient_funds processing_error issuer_not_availableFinal. The card won't work again.
The card was reported lost or stolen, or it's no longer valid. Only a new card fixes it. Recoura covers these.
lost_card stolen_card pickup_cardStripe Billing won't automatically retry an invoice payment, like a subscription renewal, after these nine hard decline codes until the customer adds a new payment method. Two aren't about the card itself: authentication_required needs the customer to verify the payment, and highest_risk_level means Stripe Radar blocked it.
When the bank offers guidance, Stripe also adds an advice_code: try_again_later, do_not_try_again, or confirm_card_data, which means the customer should check their card details. For more on how Stripe retries, see our guide to Stripe Smart Retries.
Stripe decline codes
Stripe has about 50 decline codes for card payments, and they fall into a handful of groups. Stripe's decline code reference.
A temporary issue
Retryprocessing_error- An error occurred while processing the card
issuer_not_available- The bank couldn't be reached to authorize the payment
reenter_transaction- The bank couldn't process the payment, for an unknown reason
approve_with_id- The payment can't be authorized
try_again_later- Declined for an unknown reason (deprecated)
Solution: Try again. On subscriptions, Stripe's retries handle these. If the payment keeps failing, the customer should contact their bank.
Not enough funds or credit
Retry laterinsufficient_funds- Not enough funds to complete the purchase
card_velocity_exceeded- Over the card's balance, credit limit, or transaction limit
withdrawal_count_limit_exceeded - Over the card's balance or credit limit
Solution: Retry in a few days, after a payday or a card payment. If the retries run out, ask the customer to use another card.
The bank didn't give a reason
Ask the customergeneric_decline- Declined for an unknown reason, or blocked by Stripe before it reached the bank
do_not_honor- Declined for an unknown reason
call_issuerno_action_takensecurity_violationservice_not_allowed- Declined for an unknown reason
do_not_try_again- Declined for an unknown reason (deprecated)
not_permitted- The payment isn't permitted
Solution: Ask the customer to contact their bank, which only shares the details with the cardholder, or to use another card. If they just entered the card, first check whether its CVC or address check failed.
Incorrect card details
Ask the customerincorrect_cvcinvalid_cvc- Wrong security code
incorrect_numberinvalid_number- Wrong card number. Stripe Billing won't retry
incorrect_number invalid_expiry_monthinvalid_expiry_year- Invalid expiration date
incorrect_zipincorrect_address- Wrong billing postal code or address
Solution: Ask the customer to re-enter their card details. Stripe Checkout prompts them to fix it on the spot.
Needs authentication
Ask the customerauthentication_required- The bank requires authentication, such as 3D Secure
authentication_not_handled- The customer went ahead without the required authentication
Solution: Only the customer can complete this. At checkout, Stripe's payment forms usually prompt them. For renewals, Stripe Billing can email them a link to confirm the payment, if you turn that on in your settings.
Not allowed on the card
Ask the customercard_not_supported- The card doesn't support this type of purchase
currency_not_supported- The card doesn't support this currency
invalid_amount- The amount is invalid, or more than the card allows
transaction_not_allowed- Declined for an unknown reason. Stripe Billing won't retry it
Solution: Ask the customer to check with their bank or use another card. Some cards are limited to certain businesses: FSA and HSA cards, for example, often only work with healthcare providers.
The card can't be used anymore
New card neededexpired_card- The card has expired
lost_cardstolen_card- The card was reported lost or stolen
pickup_cardrestricted_card- The card can't be used, possibly because it was reported lost or stolen
invalid_accountnew_account_information_ available - The card, or the account it's connected to, is invalid
Solution: Ask for a new card. Stripe Billing won't retry lost, stolen, or pickup cards at all. For expired cards, Stripe's card updater can sometimes pull in the new details, and Stripe can email customers a month before their card expires.
The customer stopped the payment
Stop retryingstop_payment_order revocation_of_authorization revocation_of_all_authorizationsStripe describes these only as declined for an unknown reason, but their names match the card networks' stop payment responses, which usually mean the cardholder asked their bank to stop paying you.
Solution: Don't keep retrying. Stripe Billing won't retry the two revocation codes anyway. Ask the customer whether they meant to cancel.
Blocked as fraud or merchant rules
Stop retryingfraudulent- Stripe suspects the payment is fraudulent
merchant_blacklist- The payment matches a value on your Stripe block list
Solution: Show the customer a generic decline message, as Stripe advises. If you know the payment was legitimate, review your Radar rules and block list.
In-person and other codes
duplicate_transaction- A payment with the same amount and card was just submitted. Check before charging again
testmode_decline- A Stripe test card was used where a real card was needed
In-person payments on a card reader have their own PIN and tap-to-pay codes:
incorrect_pin invalid_pin pin_try_exceeded offline_pin_required online_or_offline_pin_required mobile_device_authentication_requiredTesting decline codes
To check how your integration handles declines, use these Stripe test cards in a sandbox, with any future expiration date and any three-digit CVC. Each one returns a specific decline:
4000 0000 0000 0002generic_decline4000 0000 0000 9995insufficient_funds4000 0000 0000 6975card_velocity_exceeded4000 0000 0000 0119processing_error4000 0000 0000 0127incorrect_cvc4242 4242 4242 4241incorrect_number4000 0000 0000 0069expired_card4000 0000 0000 9987lost_card4000 0000 0000 9979stolen_card
Those cards can't be saved to a customer, so they can't test a renewal. These cover the other cases:
4000 0000 0000 0341- Saves to a customer, then declines when charged. Use it to test a failed renewal
4000 0027 6000 3184- Asks for 3D Secure on every payment, including renewals
4100 0000 0000 0019- Always blocked by Stripe Radar
Stripe's testing docs list the rest. In live mode, any test card fails with testmode_decline.
FAQ
What does "Your card was declined" mean?
It's the general message for a declined card. The specific reason is the decline code on the payment, and often it's just generic_decline: the bank didn't say why.
What's the difference between generic_decline and do_not_honor?
Very little. Both mean the bank declined without giving a reason. The one difference Stripe documents is that generic_decline can also mean Stripe blocked the payment before it reached the bank.
Does Stripe retry declined payments automatically?
Only invoice payments, like subscription renewals, and only with retries turned on in Stripe Billing. It doesn't retry one-off payments made outside an invoice, or payments with one of the nine hard decline codes above until the customer adds a new card.
How many times should I retry a declined payment?
Stripe recommends no more than eight retries, and card networks set their own limits. Issuers can read extra retries as fraud, and after too many declines, Stripe returns card_decline_rate_limit_exceeded and won't let you charge the card again for 24 hours.
Can I see the bank's original response code?
Yes. The charge's outcome.network_decline_code holds the card network's raw code. On Visa, 05 means "do not honor" and 51 means "not sufficient funds." Codes vary by card network, so check the card brand before reading into one.