Payment Declined: How to Read the Gateway Response Before You Charge Again

A decline response has three layers: the decline code the issuer returned through the card network, the advice code that accompanies it, and the normalised code your gateway adds on top. The number alone is not enough, because its meaning changes between card networks. What decides whether a retry is allowed is the advice code, not the message your customer saw.

What is actually in a decline response

A decline is not one field. It is a stack of fields produced by different parties, and only one of them is designed to tell you what to do next. Stripe, which documents this structure publicly, separates network_decline_code from network_advice_code, and states that each is a 2-4 digit code supplied by the issuing bank whose meaning depends on the card network.

That last row derails more investigations than any other. "Your payment was declined, please try another card" is text you wrote. It carries no information about what happened.

Why isn't the numeric code enough on its own?

Because the same number is not the same thing on two different networks. Stripe's documentation says it plainly: the meaning of a code differs based on the card network, so the card's brand has to be taken into account when interpreting it. A code returned on a Visa card and an identical code returned on a Mastercard are not necessarily the same problem.

Two practical consequences follow:

• An internal lookup table that maps a number to text without considering the card brand will produce a wrong diagnosis some of the time.
• The code field can come back empty. Stripe notes that when no response code is received from the network, the field is returned as null. An empty code is not "no problem" - it is "no information".

The three categories that decide what happens next

The most useful code in the response is the advice code, because it was designed to answer exactly the question "and now what". In Stripe's normalisation layer it appears as an advice_code field with three documented values:

• do_not_try_again - the card was declined and should not be used again for the same transaction. The customer contacting their issuer is the only route forward.
• try_again_later - the issuer declined, but a retry is possible. This is the only category where charging again is a reasonable step.
• confirm_card_data - the decline was caused by information that was submitted incorrectly. You do not resubmit the same values; you ask the customer to verify their card.

Notice what that means. Two of the three categories say explicitly that resubmitting the same data will not produce a different result. That is precisely why a system that retries automatically after every decline works against itself.

What should you check before charging the same card again?

• The advice code, not just the decline code. If no advice code came back, treat the decline as final until proven otherwise.
• Whether the decline was caused by a value you submitted incorrectly - number, expiry or CVC. If so, the action is to correct the value, not to attempt again.
• Whether a successful charge for the same amount on the same card already exists in the last few minutes. Stripe defines duplicate_transaction for exactly this case, and its guidance is to check whether the payment already exists.
• How many attempts have already been made against this transaction, and when. Without a persistent counter there is no way to know.
• Whether the customer is present. Somebody at the checkout can be shown an error and asked for another method; a background charge has no such option.
• Whether the decline is clustered across many customers in the same window. That pattern points at the acquirer or terminal configuration, not at cards.
• Whether the transaction required 3D Secure authentication that never ran. The fix there is to run the authentication flow, not to repeat the charge.
• What your acquirer agreement says about reattempts, and what each attempt costs you.

Where the limit on retrying comes from

Card networks cap how many times a declined transaction may be resubmitted, and exceeding that cap carries commercial consequences. Stripe states in its own documentation that card networks limit the number of times a single charge can be reattempted, and that excessive retries can look like potential fraud to issuers, which raises the decline rate on legitimate charges too.

The rules that actually bind you are the card networks' and those in your acquirer agreement, and they differ by network and by decline type. This is a technical description, not legal or contractual advice - confirm your retry policy with your acquirer before you implement it in code.

What to log so the next decline takes two minutes

• The gateway's transaction identifier, not only your internal one.
• The full response body exactly as received, including every code field - even the ones you do not interpret today.
• The card brand and last four digits, so attempts can be linked to each other.
• A precise timestamp and the attempt number in the sequence.
• Whether the customer was present, and which flow the charge came from.

Without the first four, every conversation with your acquirer starts with a question you cannot answer. The difference between a business that resolves a decline in two minutes and one that gives up on it is almost always the decision to store the response body rather than only the word "failed".

What this looks like implemented properly

A charge flow that handles declines well is not more complex. It simply separates three decisions that usually get tangled together: what happened, what the customer is told, and what happens next.

• The diagnosis layer reads the response, stores it verbatim, and sorts it into one of the three categories. It is the only layer that knows about codes.
• The presentation layer receives a category, not a code, and decides what to say. Wording can then change without touching any logic.
• The decision layer determines whether and when another attempt happens, based on the category, the attempt counter, and the policy agreed with your acquirer.

That separation prevents the most common defect in payment code: one long condition that mixes the customer message, the retry decision and the interpretation of a code, which nobody dares touch six months later.

Related: Handling decline codes from Israeli gateways, Israeli payment gateways compared, Automating invoicing and payment reminders.

Sources

• Stripe - Card declines, network codes and advice codes
• Stripe - Decline codes reference