Decline codes
Stripe decline codes and what to do about each
When a card payment fails, Stripe says why with a decline code. Each guide covers what Stripe says the code means, whether a retry can work, and what Dunity does with it.
- $29/month, flat
- Cancel anytime
- Restricted Stripe key only
The guides
9 codes, grouped by what each one needs. Stripe defines many more, and its full list is in its own decline codes docs.
Worth retrying
Not on Stripe’s hard-decline list, and the cause can change. A later attempt can succeed.
- insufficient_fundsInsufficient fundsThe card doesn’t have enough money or credit for the payment. What Stripe says, whether to retry, and how Dunity times the first retry.
- generic_declineGeneric declineThe card issuer declined the payment without saying why. What Stripe says, whether to retry, and what to ask your customer to do.
- processing_errorProcessing errorAn error occurred while processing the card. Stripe’s first advice is to try again, which is what a timed retry does.
Needs the customer
A retry alone won’t settle these. The customer has to update the card, authenticate or ask their bank.
- expired_cardExpired cardThe card’s expiry date has passed. Retrying the same card can’t work, so here is what Stripe advises and how Dunity gets a new one.
- authentication_requiredAuthentication requiredThe card issuer wants the customer to authenticate the payment, such as with 3D Secure. Why a retry can’t fix it, and what does.Stripe hard decline
- card_velocity_exceededCard velocity exceededThe customer has gone over a balance, credit or transaction limit on their card. What Stripe says and what Dunity does with it.
- do_not_honorDo not honorThe card issuer declined the payment for an unknown reason. What Stripe says, how it differs from generic_decline, and what Dunity does.
Not worth retrying
Stripe’s hard declines for a card reported lost or stolen. Retries fail until there is a new card.
- lost_cardLost cardThe card was reported lost. What Stripe says, why the customer shouldn’t be told the reason, and how Dunity handles it.Stripe hard decline
- stolen_cardStolen cardThe card was reported stolen. What Stripe says, why the customer shouldn’t be told the reason, and how Dunity handles it.Stripe hard decline
Soft and hard declines
Stripe calls a decline hard when the card issuer has rejected the payment and it can’t succeed on a retry without a new payment method. Stripe’s automatic retries skip these. Anything else can still succeed on a later attempt, which is why Stripe spaces its retries out and recommends no more than eight.
Stripe’s list of hard decline codes for subscription payments:
incorrect_numberlost_cardpickup_cardstolen_cardrevocation_of_authorizationrevocation_of_all_authorizationsauthentication_requiredhighest_risk_leveltransaction_not_allowed
From Stripe’s Smart Retries docs. 3 of the 9 guides here are on it: authentication_required, lost_card, stolen_card.
What Dunity does after any decline
- Stripe tells Dunity about the failed payment, and Dunity records the invoice, the amount and the decline code.
- Dunity emails your customer once, with a link to update their card. The email doesn’t say why the payment failed.
- The first retry comes 24 hours later, or 72 hours after an insufficient_funds decline. It tries up to 5 times, and you can change the delays and the limit.
- If a retry comes back as a hard decline, Dunity stops there and marks the payment Failed. The link in the email still works for the customer.
The whole flow, including the payment wall and the win-back offer, is on how Dunity works, and what to set up in Stripe first is on the Stripe setup guide.
Decline code questions
What people ask about failed payments and Stripe’s codes.
What is a Stripe decline code?
It is the reason the card issuer gave for declining a payment, passed on by Stripe. You can see it in your Stripe Dashboard and through the API. Issuers report most declines as generic, so many payments come back with generic_decline and no more detail.
What is the difference between a soft and a hard decline?
Stripe calls a decline hard when the card issuer has rejected the payment and it can’t succeed on a retry without a new payment method. Stripe’s own automatic retries skip those. Other declines can still succeed on a later attempt.
Should I tell my customer why their payment was declined?
Not for every code. Stripe says not to report the specific reason when a card is reported lost or stolen, or when Stripe suspects fraud, and to show a generic message instead. Dunity’s default email never states a reason.
How many times will Dunity retry a declined payment?
Up to 5 attempts by default. The first retry comes 24 hours after the failure, or 72 hours after an insufficient_funds decline, and you can change the delays and the limit in Settings. Stripe recommends no more than eight retries on a charge.
Does Dunity stop retrying when a decline is a hard one?
Yes. When a retry comes back with one of Stripe’s hard declines, or needs the customer to authenticate, Dunity marks the payment Failed and makes no more attempts. The first retry still runs, because that is how Dunity finds out the card still declines this way.