Stripe Decline Code

Where to find the decline code

In the Dashboard, a failed payment shows the reason and a short suggested resolution on the payment’s detail page.

In the API there are three places, and they carry the same answer from different angles. A failed confirmation returns an error object whose decline_code gives the issuer’s reason if one was provided. The PaymentIntent keeps the most recent failure in last_payment_error, so you can read decline_code there after the fact, and the payment_intent.payment_failed webhook fires when an attempt fails. The Charge itself records the full outcome: type, reason, advice_code, network_decline_code, network_advice_code, network_status, risk_level and seller_message.

Stripe’s own example of an expired card shows how the pieces fit: network_decline_code 54, network_advice_code 03, network_status declined_by_network, reason expired_card, advice_code confirm_card_data and type issuer_declined.

Decline code, network code and advice code

These three are easy to blur, and they answer different questions.

The network decline code is the raw value from the card network, 2 to 4 digits for cards. Stripe warns that its meaning differs by card network, so you have to read it alongside the card brand. If Stripe got no response code from the network, the field is null.

The Stripe decline code is Stripe’s normalized reason, the same across networks. It is the one to build logic and reports on.

The advice code is guidance on what to do next. Stripe’s advice_code has three values: do_not_try_again (do not use this card again for the same transaction), try_again_later (the issuer declined, but a retry is possible) and confirm_card_data (some of the card information was wrong). The network also sends its own network_advice_code, which Mastercard calls a Merchant Advice Code.

Hard declines, soft declines and retries

A hard decline means the issuer has rejected the transaction and retrying will not help. Stripe Billing lists nine codes it will not automatically retry: incorrect_number, lost_card, pickup_card, stolen_card, revocation_of_authorization, revocation_of_all_authorizations, authentication_required, highest_risk_level and transaction_not_allowed. After one of these on a subscription or invoice, retries stay on the schedule but only execute once Stripe detects a new payment method.

Everything else is retryable in principle, but not without limit. Stripe notes that card networks cap how many times a single charge can be reattempted, recommends a maximum of eight retries for charges that permit them, and warns that issuers may read extra retries as possible fraud.

authentication_required is the awkward one. Stripe’s decline code reference describes it as usually triggering an authentication flow when you use Stripe’s front ends, so an on-session customer can authenticate and pay. Off session, with nobody there to complete 3D Secure, the customer has to come back and retry, which is why it sits on the Billing hard decline list.

Codes that need special handling

Three groups are worth knowing by name.

Codes you must not repeat to the customer. For lost_card, stolen_card, fraudulent and merchant_blacklist, Stripe says not to report the detailed reason and to present the payment as a generic_decline instead. Your checkout messages and support replies should follow that.

Codes that are a typo, not a refusal. incorrect_number, incorrect_cvc, incorrect_zip, incorrect_address and the invalid_expiry codes all mean the customer can fix the details and try again.

duplicate_transaction. Stripe returns it when a transaction with identical amount and card information was submitted very recently, and its advice is to check whether a recent payment already exists. That is a bookkeeping signal: you may already have the money.

Finally, generic_decline covers two very different situations. It is used when the issuer gives no reason, and also when Stripe Radar or Adaptive Acceptance blocked the payment.

Declined, blocked or invalid

Stripe sorts failed payments into three kinds, and outcome.type tells them apart.

An issuer decline (issuer_declined) reached the card network and the issuer said no. A blocked payment (blocked) never went to the issuer: Radar stopped it as too risky, or Adaptive Acceptance stopped it as unlikely to be authorized, and network_status is not_sent_to_network. An invalid request (invalid) is an integration error and usually does not even appear as a payment in the Dashboard.

Stripe notes that a blocked payment can still show on some customers’ statements as an authorization, even though Stripe neither charged the amount nor withdrew funds. The issuer usually removes it within a few days. That explains the customer who says they were charged for a payment you can see failed.

What a decline means for your books

A declined card payment is a failed attempt, not a transaction. No money entered your Stripe balance, so there is no revenue, no processing fee on a sale and nothing in the next payout. The decline code is useful for collections and support, but there is nothing to post for it.

What can matter is the record the payment was meant to settle. A one-time checkout that fails simply never becomes a sale. A subscription invoice that fails stays open and keeps showing as owed while Stripe retries it, and whether it is eventually paid, left open, marked uncollectible or voided is the question that reaches Accounts Receivable.

Bank debits are different. An ACH Direct Debit payment is pending first and can fail later with a code such as insufficient_funds, bank_account_closed or debit_not_authorized. That failure arrives after the payment looked successful, so it can undo something already recorded.