Decline Codes

When a card issuer or payment gateway refuses a transaction, it returns a decline code — a short numeric or string identifier that describes why the payment failed. Decline codes sit at the intersection of fraud prevention, authentication compliance, and retry strategy: interpreting them correctly determines whether a merchant should retry immediately, wait, update credentials, or abandon the attempt entirely and trigger a Dunning flow.

---

Hard vs. soft declines

The most operationally important distinction is between hard and soft declines.

Soft declines are temporary rejections. The most common causes are insufficient funds, a temporary issuer outage, or a generic velocity flag. Soft declines are retry-eligible within network rules. ^[1]

Hard declines signal a permanent problem: a closed account, a card reported lost or stolen, or an explicit "do not retry" instruction from the issuer. Hard declines should not be retried without cardholder action. (Slicker, June 2026)

Checkout.com encodes this distinction directly in its 5-digit response code range: 20xxx codes are soft declines (subsequent attempts may succeed), 30xxx codes are hard declines (most require issuer or cardholder action to fix before retrying). ^[2]

Stripe does not expose a hard/soft label directly. Instead it returns:

• A decline_code (one of ~50 simplified codes mapped from hundreds of ISO 8583 bank codes)
• An advice_code in outcome.advice_code with three possible values:
  • do_not_try_again — hard decline; do not retry
  • try_again_later — soft decline; retry permitted
  • confirm_card_data — incorrect card details; customer must validate before retry ^[3]

Adyen returns three fields: resultCode (Refused/Error/Cancelled), refusalReason (short text), and refusalReasonCode (numeric). An HTTP 200 response does not indicate payment success — decline information lives in the body. Adyen's security guidance: "Do not expose the details of the refusal reason to shoppers." ^[4]

---

Most common codes and their meanings

Codes 05 (Do Not Honor) and 51 (Insufficient Funds) together account for the vast majority of all declined transactions across both Visa and Mastercard networks.

Stripe decline codes (key subset)

Code	Meaning	Retryable?
generic_decline	Unknown reason or blocked by Stripe Radar / Adaptive Acceptance	Issuer-dependent
insufficient_funds	Card has insufficient funds	Yes (soft)
do_not_honor	Unknown reason; generic issuer refusal (maps to Mastercard 05)	Depends on MAC
expired_card	Card has expired	No — update via Card Account Updater
lost_card	Card reported lost	No — surface as generic_decline
stolen_card	Card reported stolen	No — surface as generic_decline
fraudulent	Stripe suspects fraud	No — surface as generic_decline
card_velocity_exceeded	Customer exceeded limit	Soft; retry after interval
authentication_required	3DS not run; issuer requires authentication	Retry with 3D Secure 2 (3DS2) flow
incorrect_cvc	CVC incorrect	Retry with corrected CVC
processing_error	Technical processing error	Yes
issuer_not_available	Issuer temporarily unreachable	Yes
duplicate_transaction	Identical charge submitted very recently	Check for existing payment

Note: Stripe instructs merchants never to surface the raw reasons for lost_card, stolen_card, fraudulent, and merchant_blacklist to customers — these should be presented as generic_decline. ^[6]

Adyen refusal reason codes (key subset)

Code	Reason	Notes
2	Refused (generic)	Maps to issuer-specific refusals
5	Blocked Card	Hard decline
6	Expired Card	Hard; route to Card Account Updater
11	3D Not Authenticated	3DS not run or failed
12	Not Enough Balance	Soft
20	FRAUD	Pre-auth risk score ≥100; hard
23	Transaction Not Permitted	Maps to issuer codes 57 and 58
26	Revocation Of Auth	Shopper cancelled subscription (R0/R1/R3)
27	Declined Non Generic	Catch-all for Mastercard "05: Do Not Honor" and other non-mappable codes
38	Authentication Required	Issuer declined exemption; retry with 3DS
42	3DS Authentication Error	3DS protocol failure; retry or try different method
46	Blocked by Adyen to Prevent Excessive Retry Fees	Adyen's internal protection fires before the network; do not retry
50	Token Revoked	Shopper disabled recurring charge token

^[4]

Checkout.com Recommendation Codes

Checkout.com maps Mastercard and Visa response codes to three recommendation codes:

• 01 — Updated or additional information required (expired card, updated info, authentication may improve approval)
• 02 — Try again later (insufficient funds, credit risk decline, issuer velocity)
• 03 — Do not try again (account closed, suspected fraud, recurring agreement cancelled)

^[7]

---

Network retry rules

Both Visa and Mastercard publish explicit rules on how many times a declined transaction may be retried, with financial penalties for merchants who exceed them.

Retry caps

For hard declines, both networks permit only 1 attempt. (Slicker, June 2026)

Visa groups response codes into four retry categories:

1. Issuer will never approve — do not retry (e.g. lost card, stolen card, closed account, revocation orders)
2. Issuer cannot approve at this time — try again later (e.g. insufficient funds, suspected fraud, system malfunction)
3. Issuer cannot approve based on details provided — provide updated/corrected information (e.g. expired card, incorrect PIN, 3DS required)
4. Generic response codes — try again later

^[9]

Mastercard Merchant Advice Codes (MACs)

Mastercard publishes Merchant Advice Codes (MACs) that give transaction-level retry instructions. Visa does not publish an equivalent set. (Slicker, June 2026)

Key MACs (returned by Checkout.com in processing.partner_merchant_advice_code):

• MAC 01 — Updated or additional information required
• MAC 02 — Try again later (insufficient funds, credit risk, velocity)
• MAC 03 — Do not try again (account closed, suspected fraud, recurring cancelled)
• MAC 21 — Do not try again (payment cancellation)
• MAC 24 — Retry after one hour
• MAC 25 — Retry after 24 hours
• MAC 26 — Retry after two days
• MAC 27 — Retry after four days
• MAC 28 — Retry after six days
• MAC 29 — Retry after eight days
• MAC 30 — Retry after 10 days

^[7]

Retry penalty fees

Retrying beyond network limits incurs per-transaction penalty fees.

Visa VAMP (Visa Acquirer Monitoring Program): Flags merchants exceeding a 15% decline rate or 1,000 monthly decline transactions. Fines: $5,000–$75,000 per month until compliant. (as-of 2026-07-08) (Slicker, June 2026)

Mastercard January 2026 expansion: Starting January 2026, Mastercard expanded the MAC 03/21 excessive authorization fee to apply to all declined card-not-present transactions bearing these codes, not only repeated retries. Subscription, SaaS, digital goods, and nonprofit organisations with automated retry logic are specifically flagged. ^[11] (as-of 2026-01)

Fees accrue regardless of whether the retried transaction eventually succeeds. At high volume: a business retrying 50,000 transactions beyond Mastercard's threshold could face $50,000–$100,000 in monthly penalty fees. (Slicker, June 2026)

Visa's Transaction Processing Rules (18 April 2026 edition) are publicly available. ^[12] (as-of 2026-04-18)

Adyen code 46 ("Transaction Blocked by Adyen to Prevent Excessive Retry Fees") represents Adyen's own internal pre-emptive blocking — the gateway fires before the transaction reaches the network to protect the merchant from penalty fees. (Adyen Docs, as-of 2026-07-08)

Stripe's Adaptive Acceptance feature similarly blocks payments proactively when probability of authorisation is low; the network_status is not_sent_to_network. ^[13]

---

Retry strategy by code type

The Stripe docs recommend a maximum of eight retries for charges that permit retries; exceeding this may be seen as potential fraud by issuers, increasing declines on legitimate charges. ^[3]

Optimal retry timing signals from practitioner sources (flagged as potentially superseded):

• Insufficient funds (soft): US Monday/Tuesday mornings (post-weekend deposits); Western Europe 1st/15th of month (salary cycle); Australia Thursday/Friday mornings.
• Temporary issuer outages: retry window 2–4 hours.
• Expired card: route through Card Account Updater first; retry within 24 hours once updated credentials confirmed.
• MAC 03 / MAC 21: do not retry at all; route to Dunning / customer comms.

Staggered retry logic over 24–72 hours has been cited as recovering up to 28% of declined transactions. Overall recovery with ML retries + dunning + card updater + Network Tokenisation is cited at 50–80% of soft declines.

[!unverified] Recovery rate figures (28%; 50–80%) cited in search result summaries without a single named primary source. Include for directional signal only.

---

3DS / authentication vs. authorisation declines

3D Secure 2 (3DS2) is the authentication layer that sits before authorisation. If authentication fails or is abandoned, authorisation is not attempted. ^[14]

Key codes at the authentication/authorisation intersection:

• Stripe authentication_required: issued when an issuer requires 3DS but it was not run. Also issued when an issuer rejects a transaction even after successful authentication (customer must then contact their issuer). (Stripe Docs, as-of 2026-07-08)
• Adyen code 38 (Authentication Required): issuer declined an exemption request under Strong Customer Authentication (SCA) rules and requires full 3DS. Action: retry with 3DS. (Adyen Docs, as-of 2026-07-08)
• Adyen code 42 (3DS Authentication Error): 3DS failed at the network or issuer side. Action: retry or try a different payment method. (Adyen Docs, as-of 2026-07-08)
• Checkout.com code 20154: 3DS authentication required (Category 3 — update/correct information). (Checkout.com Docs, as-of 2025-02-26)

A "soft decline via 3DS" occurs when an issuer soft-declines an authorisation exemption request (e.g. TRA, low-value), requiring the merchant to re-attempt with full 3DS. The France Banque de France effective March 10, 2025 issued guidance that issuers will soft-decline all customer-initiated authorisation exemption requests except those requested via EMV 3DS. (Adyen Docs, as-of 2025-03-10)

---

Benchmarks

• Average decline rate across recurring payment attempts: ~15% (as-of March 2025, Chargebacks911 citing Visa/Mastercard data, https://chargebacks911.com/credit-card-decline-rates/, updated February 2026)
• Ecommerce industry decline rate range: up to 17%; a healthy decline rate is typically below 10% (search result summaries)
• Subscription/recurring payments decline rate: 15–25% (as-of November 2025, GR4VY, https://gr4vy.com/posts/credit-card-decline-codes-in-subscription-billing-how-to-read-them/) — approximately 3× the one-time purchase decline rate of 4.5–5%
• Credit card declines as a cause of Involuntary Churn and subscription cancellations: 20–40% (Chargebacks911 citing ProfitWell survey; as-of February 2026)

---

What practitioners report

A recurring merchant frustration pattern on Shopify Community (2023–2025) centres on do_not_honor spikes with no actionable resolution from Shopify support:

• UK-based merchants selling into the US and Danish/Scandinavian merchants have reported sudden spikes to 90%+ do_not_honor declines via Shopify Payments. One merchant tested by switching to a third-party Stripe gateway and observed no declines, concluding the issue was Shopify Payments-specific routing rather than issuer-side. ^[15]

• Shopify support consistently deflected to "ask the customer to call their bank" — a response merchants across four separate threads explicitly called "worthless." No root cause escalation was documented in any thread. (Shopify Community threads, 2023–2025)

• Adyen reports a 300% increase in recovered payments since deploying ML-backed auto-retries (as-of July 2021, noted in Adyen Knowledge Hub, https://www.adyen.com/knowledge-hub/marginal-gains-recovering-payments).

---

Key terms

Term	Meaning
Hard decline	Permanent rejection; do not retry without cardholder action
Soft decline	Temporary rejection; retry-eligible within network rules
Decline code	PSP-simplified reason code (e.g. Stripe's do_not_honor)
Network decline code	Raw 2–4 digit issuer code (e.g. ISO 8583 code 05)
Advice code / MAC	Network-level instruction on whether and when to retry
VAMP	Visa Acquirer Monitoring Program — penalty programme for high decline rates
Excessive Attempts	Mastercard programme penalising merchants who retry beyond network limits
refusalReasonCode	Adyen's numeric decline code (0–50)

References

1. Slicker, June 2026: — www.slickerhq.com/resources/blog/visa-mastercard-payment-retry-rules
2. Checkout.com Docs, as-of 2026-07-08 — www.checkout.com/docs/developer-resources/codes/api-response-codes
3. Stripe Docs, as-of 2026-07-08 — docs.stripe.com/declines/card
4. Adyen Docs, as-of 2026-07-08 — docs.adyen.com/development-resources/refusal-reasons
5. as-of February 2026 update — chargebacks911.com/credit-card-decline-rates
6. Stripe Docs, as-of 2026-07-08 — docs.stripe.com/declines/codes
7. Checkout.com Docs, as-of 2026-01-07 — www.checkout.com/docs/developer-resources/codes/recommendation-codes
8. November 2025 — gr4vy.com/posts/credit-card-decline-codes-in-subscription-billing-how-to-read-them
9. Checkout.com Docs citing Visa, as-of 2025-02-26 — www.checkout.com/docs/developer-resources/codes/visa-response-codes
10. citing Congrify — congrify.com/card-scheme-penalty-fees
11. Verisave, published August 2025; Congrify — verisave.com/blog/mastercard-excessive-authorization-rules-2026
12. Visa — usa.visa.com/dam/VCOM/download/about-visa/visa-rules-public.pdf
13. Stripe Docs, as-of 2026-07-08 — docs.stripe.com/declines
14. PCI Proxy — www.pci-proxy.com/blog-posts/blog-3d-secure-authentication-guide
15. Shopify Community, March 2024–December 2024 — community.shopify.com/t/ongoing-shopify-payments-issue-do-not-honor/302481