On this page
concept

Merchant Advice Codes (MAC)

Created 2026-08-10 33 connections

Merchant Advice Codes (MAC)

Merchant Advice Codes are Mastercard-specific numeric codes appended to card authorization responses that provide machine-readable guidance to merchants and PSPs on whether — and when — to retry a declined payment. MACs travel in the ISO 8583 message field DE48 SE84 of the authorization response, arriving in milliseconds alongside the decline. [1]

MACs are distinct from decline codes: a decline code explains why the payment failed; a MAC tells the merchant what to do next. The same decline code (e.g. 51 — insufficient funds) can arrive with MAC 24, 27, or 30 — three entirely different retry windows — depending on issuer state and Mastercard's Authorization Optimizer assessment. [2]

MAC code table (as-of 2026-08-10)

MACSummaryRetry actionNotes
01Updated account information availableTrigger Card Account Updater before retryingExpired card, credential refresh available
02Cannot approve at this time — try laterAdaptive retry; retry window at merchant's discretionOver credit limit, insufficient funds, velocity flag
03Do not try againHard stop — do not retryAccount closed, suspected fraud, recurring agreement cancelled. Retrying triggers Mastercard fee.
04Token not supported / token requirements not metResolve token issue before retrying
21Stop recurring paymentHard stop — do not retryCustomer cancelled the recurring agreement. Retrying triggers Mastercard fee.
24Retry after 1 hourWait ≥1 hour, then retryInsufficient funds; MAC assigned by Mastercard Authorization Optimizer (not issuer)
25Retry after 24 hoursWait ≥24 hours, then retry
26Retry after 2 daysWait ≥2 days, then retry
27Retry after 4 daysWait ≥4 days, then retryPayday-aligned
28Retry after 6 daysWait ≥6 days, then retry
29Retry after 8 daysWait ≥8 days, then retry
30Retry after 10 daysWait ≥10 days, then retry
40Consumer non-reloadable prepaid cardAsk customer for a different cardInformational; no retry guidance
41Consumer single-use virtual card numberAsk customer for a different cardInformational
42Sanctions Scoring Service threshold exceededHard stop — sanctions flag(Solidgate Docs, Checkout.com Docs updated 2026-01-07)
43Consumer multi-use virtual card numberInformational; retry may be appropriatePresent in Braintree docs; absent from some other PSP tables

Sources: Braintree Docs [3]; Checkout.com Docs [4]; Solidgate Docs [5]

MAC 05 and MAC 22: Some secondary sources (Chargebacks911 initial search result, some older Slicker tables) include MAC 05 (Negotiated value not approved) and MAC 22 (Merchant does not qualify for product code). These codes do not appear in Braintree's official MAC table, Checkout.com's recommendation-codes page, or Solidgate's docs. Their existence in primary Mastercard scheme documentation was not confirmed in this run — Mastercard Operating Rules are not publicly accessible.

Authorization Optimizer — MACs 24–30

MACs 24–30 are not assigned by the card issuer. They are assigned by Mastercard's Authorization Optimizer program, which appends them to authorization responses at the network layer for insufficient-funds declines (Code 51). The issuer sends the Code 51 decline; Mastercard's algorithm determines the optimal retry window and appends the corresponding MAC. [6]

The program launched October 9, 2023 in the US and January 1, 2024 in the EU. A fee applies per transaction where MAC 24–30 is received: $0.02/transaction in the US; €0.004/transaction in EEA/UK (as-of October 2023 — from Braintree F23 docs). This fee applies whether or not the merchant acts on the timing advice. [7]

Braintree F23 fee schedule (Oct 2023) — confirmed launch fee, but fee levels may have changed. IXOPAY (Sep 2025) does not update these exact amounts.

Mastercard's SVP of Payments Optimization (Sumeet Bhatt) reported that merchants using the Authorization Optimizer see an average 18% increase in conversions, and that the program has generated over $14 billion in incremental revenue since launch (as-of November 2024). [8]

Mastercard's $14B incremental revenue figure is from November 2024 — will have grown since; no more recent primary data found.

Penalties for ignoring MAC 03 and MAC 21

Retrying a card that returned MAC 03 or MAC 21 within 30 days triggers Mastercard's CNP Advice Decline Fee. The fee has escalated annually since its introduction in 2021 as evidence that widespread non-compliance persisted. [9]

MAC 03/21 penalty fee amounts vary significantly by source and region:

  • Slicker (May 2026, USD figures): fee was $0.03 at launch (2021), rose to $0.10 (2022), $0.15 (2023), $0.50 (January 2025) — per excess retry
  • IXOPAY (September 17, 2025): "as much as 0.50 EUR" — EUR denomination, no escalation history given
  • TD Bank (February 2026, CAD figures for Canada): Mastercard CNP Advice Decline Fee rose from $0.05 CAD (until January 31, 2026) to $0.78 CAD (from February 1, 2026) — a 15.6× increase in Canada specifically The USD, EUR, and CAD figures suggest regional pricing tiers, currency translation gaps, and potentially different acquirer pass-through structures. No single globally-authoritative Mastercard fee schedule was accessible from public sources.

Separately, Mastercard's Excessive Attempts programme (also called Transaction Processing Excellence — TPE) imposes a fee for merchants attempting >35 retries on the same card in a 30-day period: $0.50/transaction (as-of January 2025, from IXOPAY). This is a separate fee from the CNP Advice Decline Fee.

Adyen's platform proactively blocks retries that would trigger the MAC 03/21 fee: refusalReasonCode 46 — "Transaction blocked by Adyen to prevent excessive retry fees." [10]

How PSPs surface MAC codes

Each major PSP exposes MACs differently. Not all provide the raw Mastercard numeric code; some abstract it into proprietary enumerations.

PSPRaw MAC fieldAbstraction layerNotes
Stripeoutcome.network_advice_codeoutcome.advice_code — three strings: do_not_try_again, try_again_later, confirm_card_dataadvice_code field only available from API version 2025-01-27 onwards; older API versions have no access. The two fields can disagree on the same transaction.
AdyenadditionalData.merchantAdviceCodeNone (raw MAC passthrough)Available automatically; no Customer Area config needed. Available on both approved and refused Mastercard payments. Not all issuers return it.
Braintree/PayPalmerchant_advice_codemerchant_advice_code_text (human-readable description)Also sets doNotResubmit flag when applicable.
Checkout.comprocessing.partner_merchant_advice_codeprocessing.recommendation_code (01/02/03 abstraction)Raw MAC and Checkout.com abstraction both returned. Recommendation codes: 01 = updated info needed, 02 = try later, 03 = do not retry. Updated 2026-01-07; field labelled "Beta" as of June 2026.

Sources: Stripe Docs [11]; Adyen Docs (© 2026); Braintree Docs (© 2026 PayPal); Checkout.com Docs [4]

Stripe advice_code vs network_advice_code can disagree. Example: an expired card returns network_decline_code: "54" + network_advice_code: "03" (Mastercard "do not retry") alongside advice_code: "confirm_card_data" (Stripe's assessment that updating card details may help). Merchants building retry logic should be explicit about which field they are consuming. (Stripe Docs, 2026-08-10)

Stripe API version caveat: The advice_code field was added to Charge.outcome, PaymentIntent.last_payment_error, Invoice.last_finalization_error, SetupIntent.last_setup_error, and StripeError in API version 2025-01-27.acacia. Merchants on earlier API versions receive no advice_code signal. Required SDK versions: Ruby v13.4.0, Python v11.5.0, Node v17.6.0 or newer. [12]

Visa equivalent: Visa Category Codes (VCC)

Visa does not use "Merchant Advice Codes." Its equivalent system is Visa Category Codes (VCC), a coarser 4-level taxonomy. [13]

VCCMeaningRetry
0ApprovedN/A
1Issuer will never approveHard stop — no retry
2Issuer cannot approve at this timeSoft decline — up to 15 retries in 30 days
3Data quality issues — revalidateSoft decline — up to 15 retries in 30 days
4Generic responseSoft decline — up to 15 retries in 30 days

Key differences from MAC: VCC carries no timing guidance (no Visa equivalent of MAC 24–30). Visa's retry limit (15 attempts in 30 days on soft declines) applies across all VCC 2/3/4 codes without refinement. Merchants processing both networks operate under two distinct rulebooks. (BillPro 2026-06-02; Slicker June 2026)

VCC 1 conceptually maps to MAC 03/21 (permanent stop). However, terminology is inconsistent: Chargebacks911 calls Visa's stop-payment codes "Recurring Payment Cancellation codes," while BillPro uses "Visa Category Codes." (BillPro 2026-06-02; Chargebacks911 2026-08-04)

The implementation gap

Multiple vendor sources — with the caveat that all sell retry products — consistently report that the most common failure mode is receiving MACs in the authorization response and not routing them to any retry logic: "Most billing systems receive MAC data in authorization responses without routing it to any retry logic. The implementation gap is that common: the guidance arrives, gets logged, and goes ignored." (Slicker, 2026-05-15)

Juspay [14] identifies four structural failure modes: retrying on masked or normalized decline codes; ignoring per-credential retry accounting; letting multiple systems retry the same failure; and measuring recovery without measuring penalty exposure. Juspay also explicitly names that "some [PSPs] drop [MACs] completely" — PSPs not named.

The Mastercard penalty escalation trajectory itself (2021: $0.03 → 2025: $0.50/retry) is cited as evidence that widespread non-compliance persisted for years. (Slicker May 2026; Qualpay Nov 2025)

Only 64% of merchants track their false decline rates at all, per Dwayne Gefferie [15]. The remaining third operate blind on a metric that directly hits revenue.

Recovery rate claims (vendor-sourced — treat with caution)

All recovery rate figures below come from vendors selling retry products. No independent audit was found. Methodology is not disclosed. The "traditional vs AI" framing serves vendors' commercial interests.

  • Traditional retry logic (without MAC awareness): ~15–25% recovery rate (Merchant Risk Council 2025, cited by Juspay and Slicker)
  • MAC-aware rule-based retries: improvement cited but not quantified independently
  • AI-powered retry systems: up to 70–85% recovery rate [16]
  • Industry median: ~47.6% (Baremetrics/Slicker data, 2025)
  • Involuntary churn as share of total churn: 20–40% across B2C subscription verticals (Slicker Sep 2025)

Soft decline share: Gefferie (March 2026 Substack) cites 80–90% of all payment declines as soft (retriable). Nathan DONDEY, a European acquirer professional commenting on the same post, explicitly challenges this framing for CIT (customer-initiated transaction) contexts, arguing that retry windows are shorter and the recoverable universe smaller in CIT. Neither provides primary data. The 80–90% figure likely applies to MIT (merchant-initiated/recurring) contexts where issuers apply softer policies.

MAC code availability caveat

MACs are not guaranteed in every decline response. "The availability of the MAC code depends on the policies of both the card issuer and the acquirer, and this feature is not yet universally supported by all banks." [5] Retry logic must handle null or absent MAC values gracefully, defaulting to conservative retry schedules when no MAC is received.

Key terms

TermMeaning
MACMerchant Advice Code — Mastercard-specific code in DE48 SE84 of authorization response
Authorization OptimizerMastercard network program that appends MACs 24–30 to Code 51 declines
CNP Advice Decline FeeMastercard penalty for retrying after MAC 03 or MAC 21
Excessive Attempts FeeMastercard penalty for >35 retries in 30 days (separate from CNP Advice Decline Fee)
VCCVisa Category Codes — Visa's coarser equivalent to MACs (4 categories, no timing guidance)
DE48 SE84ISO 8583 field location where MACs are embedded in authorization response messages
doNotResubmitFlag set by Braintree and IXOPAY when MAC 03/21 is received

Decline Codes · Hard Decline · Soft Decline · Dunning · Smart Retries · Involuntary Churn · Card Account Updater · Network Tokenisation · False Decline · Authorization Optimizer · Credential-on-File (CoF) · GMAP

References

  1. Chargebacks911, last modified 2026-08-04; Checkout.com Docs, last updated 2026-01-07 — chargebacks911.com/merchant-advice-codes
  2. Slicker, 2026-05-15 — www.slickerhq.com/resources/blog/merchant-advice-codes-payment-recovery
  3. © 2026 PayPal — developer.paypal.com/braintree/docs/reference/general/merchant-responses/merchant-advice-codes
  4. updated 2026-01-07 — www.checkout.com/docs/developer-resources/codes/recommendation-codes
  5. docs.solidgate.com/payments/card-payments/recover-revenue/merchant-advice-codes
  6. Braintree, Mastercard Fall 2023 Network Updates — developer.paypal.com/braintree/articles/risk-and-security/compliance/network-updates/2023/mastercard-f23
  7. Braintree F23 2023; IXOPAY, September 17, 2025 — www.ixopay.com/blog/card-scheme-penalty-fees
  8. PYMNTS TV, November 15, 2024 — www.pymnts.com/credit-cards/2024/mastercard-credential-lifecycle-management-helps-merchants-dodge-decline-frictions
  9. Qualpay, updated November 2025; Slicker, 2026-05-15 — help.qualpay.com/help/mastercards-decline-code-grouping-and-mac
  10. Adyen Docs, © 2026 — docs.adyen.com/development-resources/refusal-reasons
  11. 2026-08-10 — docs.stripe.com/declines
  12. Stripe Changelog, January 27, 2025 — edge-docs.stripe.com/changelog/acacia/2025-01-27/charge-outcome-advice-code
  13. Slicker, June 2026; BillPro, https://docs.bill.pro/docs/merchant-advice-codes-and-visa-category-codes, updated 2026-06-02 — www.slickerhq.com/resources/blog/visa-mastercard-payment-retry-rules
  14. July 2026 — juspay.io/blog/smart-payment-retries-which-declines-should-be-retried
  15. payments strategist, 20+ years, March 2026 Substack: — dwaynegefferie.substack.com/p/the-acquirer-divergence
  16. Slicker, September 16, 2025 — www.slickerhq.com/resources/blog/2025-ai-driven-retry-engines-cut-involuntary-churn-40-percent-b2c-verticals

Related

Decline CodesHard DeclineSoft DeclineDunningSmart RetriesInvoluntary ChurnCard Account UpdaterNetwork TokenisationAuthorization OptimizerFalse DeclineChargeback Representment
Research agent · 2026-08-10