Credit card decline codes: decide what to stop, retry, or route.

Start with the action owner, not the wording

“Do not honor” is not a complete diagnosis

Stripe describes do_not_honor as a card issuer decline with an unknown reason and directs the customer to contact the issuer. Adyen likewise documents refusal reasons returned through its platform and notes that some issuer responses are generic. A merchant should not translate a generic decline into “insufficient funds,” “fraud,” or another definite explanation without evidence.

A useful customer message is: “Your bank did not approve this payment. Please contact your bank or try another payment method.” That states the result without exposing internal risk logic or blaming the customer. Support can retain the provider, merchant account, transaction ID, response code, timestamp, amount, currency, checkout version, and correlation ID for investigation without storing prohibited card data.

Hard decline vs. soft decline is a workflow decision

Braintree's processor-response documentation separates hard and soft declines for its own platform and warns merchants to use the provider response rather than an invented interpretation. In practice, a hard decline is treated as non-retryable with the same credentials, while a soft decline might be recoverable after time, authentication, or customer action. That distinction is not a universal card-network code table.

Ask the provider whether it exposes network or merchant advice, a normalized code, a raw response, and a recommended action. Braintree's separate Merchant Advice Code documentation is one example of provider guidance that can indicate whether to update account information, retry later, or stop recurring attempts. Use advice only when it is present for the specific transaction and current provider integration.

Separate issuer declines from other payment failures

Use a retry runbook that cannot create duplicate charges

1. Identify the original attempt. Join the order, payment intent or transaction, amount, currency, merchant account, payment method reference, and provider response.
2. Check authoritative state. Determine whether the original request failed, remains pending, later succeeded, was reversed, or has an unknown outcome.
3. Honor stop conditions. Stop after cancellation, authorization withdrawal, provider no-retry advice, a replacement payment, or any required compliance or risk hold.
4. Fix before retrying. Correct validation, authentication, customer input, merchant configuration, or integration errors rather than repeating the same request.
5. Retry only through approved logic. Apply the provider's current timing and attempt guidance for the merchant's region, payment method, and billing model.
6. Use an idempotent payment design. Repeated client clicks, network timeouts, and webhook redelivery should reconcile to one intended charge, not create independent sales.
7. Record the outcome. Link each attempt, response, customer message, order state, and final payment or abandonment result.

Give customers a message they can act on

Avoid telling the shopper a card is fraudulent, empty, blocked, or invalid unless the provider safely exposes that exact customer-facing reason. Keep internal risk signals out of customer messages. If the result is uncertain, do not invite another attempt until the merchant verifies whether the first request succeeded.

Recurring billing needs stricter stop conditions

For subscriptions, a recovery sequence must respect the customer's authorization and current account state. Do not retry after cancellation, revoked authorization, a provider stop-billing instruction, or replacement payment. Update the retry plan when the customer supplies a new payment method, and keep the invoice, subscription, notices, attempts, and final status in one audit trail.

Use the subscription payment processing guide for consent and cancellation controls. Provider-supported account updater, network token, or dunning features can be part of a program, but availability and outcomes depend on the provider, network, issuer, region, and approved setup.

Measure decline recovery without hiding the cost

Track unique orders and customers separately from authorization attempts. Useful measures include initial approvals, issuer declines, merchant or gateway rejections, authentication failures, technical unknowns, retries by response class, recovered orders, customer-updated methods, duplicate attempts blocked, duplicate charges, refunds, disputes, and support contacts.

A lower decline percentage does not by itself prove a better provider or safer retry strategy. Compare consistent cohorts by country, payment method, new versus returning customer, subscription versus one-time sale, authentication path, amount, issuer region, and provider route. Count final paid orders and downstream refunds or disputes, not only successful authorization attempts.

Questions to ask the provider

1. Does the API expose a normalized code, raw processor response, network or merchant advice, and a customer-facing message separately?
2. Which responses are retryable for this payment method, country, merchant account, and recurring or one-time model?
3. Which response or advice requires stopping future attempts?
4. How should the integration resolve a timeout or unknown authorization state before retrying?
5. Which identifiers and logs are safe and useful for support without retaining sensitive card data?
6. How are authentication failures distinguished from authorization declines?
7. Can reports separate unique orders, initial attempts, retries, final approvals, duplicate blocks, refunds, and disputes?

No decline-code guide can guarantee recovery, authorization, pricing, settlement, or uninterrupted processing. Code labels, mappings, detail, retry rules, authentication flows, and advice availability can change and vary across providers, acquirers, networks, issuers, regions, and use cases.