Merchant advice codes: what each Mastercard MAC tells you to do

A declined Mastercard payment often carries two answers. The response code says why the issuer declined, usually in generic terms. The merchant advice code says what the issuer wants you to do next: update the card, wait, or stop. Most retry and dunning systems read the first and ignore the second, which is how merchants end up retrying cards the issuer has already refused for good, and paying a network fee for each attempt.

This article explains what merchant advice codes are, where they arrive, what each one means, how Visa handles the same idea, and how to turn the codes into routing and dunning rules. For the general split between retryable and final declines, see our guide to soft and hard declines; for retry logic across providers, see cascading and decline recovery.

What is a merchant advice code?

A merchant advice code (MAC) is a two-digit value that a Mastercard issuer, or Mastercard itself, attaches to an authorization response to advise the merchant on its next step. Mastercard’s developer documentation defines the field as the action taken by the issuer or its advice to the merchant, and says it is present when the issuer, rather than the Mastercard network, declined the transaction.

The MAC does not replace the response code. A decline still carries its ISO 8583 response code, such as 05 do not honor or 51 insufficient funds. The MAC adds an instruction on top. Stripe’s list of network codes shows why that matters: Mastercard can return the same code 05 with MAC 01, 03 or 21, and each calls for a different action.

Where does the MAC arrive, and how do providers pass it on?

In the authorization message, the MAC sits in data element 48, subelement 84. Chargeback Gurus describes the retry-timing codes 24 to 30 as new values sent to that existing field under Mastercard release AN 6042, an Authorization Optimizer enhancement for select card-not-present payments.

Merchants rarely see DE 48 directly. Each provider exposes the value under its own name, and some only on request:

Provider	Where the MAC appears	Note from the provider’s documentation
Stripe	network_advice_code on the charge outcome	Also returns its own normalised advice_code
Adyen	merchantAdviceCode in additional data	Not all Mastercard issuers return it; no setting needed
Checkout.com	processing.partner_merchant_advice_code	Also returns a recommendation code for Mastercard and Visa

Two details from those pages are worth knowing. Adyen says the MAC can be returned for approved as well as refused Mastercard payments, so an approval can still carry information, such as a prepaid card flag. And Adyen warns that raw responses must not be shown to customers, to prevent misuse of the data. Store the MAC; do not display it.

What does each merchant advice code mean?

Mastercard’s developer documentation lists the values. The actions below follow the guidance in Adyen’s, Checkout.com’s and PayPal’s documentation.

MAC	Meaning	What to do
01	New account information available	Get updated card details, for example through an account updater, before retrying
02	Cannot approve at this time, try again later	Retry later; PayPal and Adyen suggest after 72 hours
03	Do not try again	Stop; ask the customer for another card or method
04	Token requirements not fulfilled for this token type	Fix the token data or use another credential
21	Payment cancellation	Stop the recurring series; do not resubmit
24	Retry after 1 hour	Insufficient funds; one retry after the wait
25 to 30	Retry after 24 hours, 2, 4, 6, 8 or 10 days	Insufficient funds; schedule the retry for that time
40	Consumer non-reloadable prepaid card	Informational
41	Consumer single-use virtual card number	Informational; do not store it for later payments

Mastercard’s list marks 24 to 30 as “Mastercard use only”, Checkout.com adds 42 for a sanctions score above threshold, and Adyen treats 40 to 43 as informational, needing no action. Expect the list to grow, and treat an unknown value as “no advice” rather than as permission to retry.

Codes 40 and 41 describe the card rather than the decline. They are useful for subscriptions: a single-use virtual card will not work for the next renewal, so the customer needs to add another card at sign-up, not after the first failed charge.

How do MACs combine with decline codes?

Read the MAC for the decision and the response code for the reason. Stripe’s table of Mastercard codes shows typical pairs:

Response code	With MAC	Practical reading
05 do not honor	01	Card details changed; update and retry
05 do not honor	03 or 21	Final; stop and ask for another method
51 insufficient funds	02	Retry later
51 insufficient funds	03	Final, despite looking like a funds problem
54 expired card	01	Updated card data exists; fetch it
79 lifecycle decline	03	Account credentials not found; do not retry
83	02	Retry the transaction later

The second row and the fourth are the reason to read both fields. A 05 or a 51 looks retryable on its own. With MAC 03 attached, it is not. When the two disagree, follow the MAC on whether to retry and use the response code to choose the customer message.

When no MAC arrives, fall back to your rules for the response code. Our article on soft and hard declines lists which codes are worth a second attempt.

How does Visa handle the same idea?

Visa has no separate advice field. Instead, the response code itself falls into a category that sets the reattempt rules. Visa’s 2020 rules notice explains that, from April 2020, Visa grouped authorization response codes into four categories and required issuers to send descriptive codes, and that merchants should manage reattempts based on those categories. Category 1 means the issuer will never approve, and no reattempt is permitted.

Checkout.com’s documentation shows how the two models can be aligned. It returns one recommendation code for both networks: 01 for updated information needed, 02 for retry later and 03 for do not retry, whichever network the card belongs to. Stripe does something similar with its own advice_code: do_not_try_again, try_again_later or confirm_card_data. If you use several providers, build the same three-way decision yourself, from MACs for Mastercard and categories for Visa, so a retry rule means the same thing whichever provider processed the payment.

What does retrying after MAC 03 or 21 cost?

Mastercard charges for it under its Transaction Processing Excellence program. According to PayPal’s May 2026 guidance, a fee applies when a payment declined with MAC 03 or 21 is attempted again within 30 days and declined again with 03 or 21. PayPal gives the fee as USD 0.03 in the US and Canada, EUR 0.50 in Europe, and USD 0.50 in Latin America, the Middle East and Africa and Asia Pacific.

The rule has tightened. TabaPay reports that from 1 January 2026, Mastercard removed the same-amount condition from the criteria in the US and Canada: a retry for a different amount, on the same card at the same merchant, now counts too.

MAC 03 and 21 retries also count towards Mastercard’s separate limits on excessive attempts per card. Our soft vs hard declines article lists those thresholds and the regional fees.

How do you turn MACs into routing and dunning rules?

Map every MAC to one of a small set of actions, then let your retry, cascade and dunning logic act on the action, not on the raw code.

1. Stop (03, 21). End the attempt chain at once, on every provider. For a subscription, mark MAC 21 as a cancellation by the cardholder and stop the series; for 03, send the customer to update their payment method.
2. Update first (01, 04). Ask an account updater or the token service for new card data, or ask the customer. Retry only once the data has changed.
3. Retry at the advised time (24 to 30). Schedule exactly one retry at the time the code names. Do not cascade it to another acquirer: the account is short of funds whoever asks.
4. Retry later (02). Wait, then retry once. For renewals, align the wait with your dunning schedule.
5. No advice. Use your response-code policy, within Visa’s and Mastercard’s attempt limits.

Keep one attempt counter per card across all providers, and keep the last MAC with it, so a stop on one route also stops the others. Our guide to subscription payment recovery covers the dunning messages that pick up where retries end.

Worked example: a month of renewal declines

Example figures, for illustration only.

A software subscription business that acquires in Europe gets 2,000 Mastercard declines on renewals in a month.

MAC received	Declines	Code-aware action	Attempts in 30 days
None	900	Response-code policy	900
01	220	Account updater, then one retry	220
02	180	One retry after 72 hours	180
03	260	Stop; dunning email	0
21	40	Cancel the series	0
24 to 30	400	One retry at the advised time	400
Total	2,000		1,700

Its old policy retried every decline once a day for three days: 6,000 extra attempts. The 300 declines with MAC 03 or 21 produced 900 of them. If the issuer answers each with 03 or 21 again, as it usually will, that is 900 × EUR 0.50, or EUR 450 a month in Mastercard fees, for attempts that could not succeed.

The code-aware policy sends 1,700 attempts, none of them after a stop code, and every insufficient funds retry lands at the time the issuer suggested rather than the next morning.

What are the common mistakes?

• Reading only the response code. A 05 or 51 with MAC 03 is final. Without the MAC, it looks retryable.
• Cascading a stop code. MAC 03 describes the issuer’s decision on the card, and every acquirer reaches the same issuer.
• Changing the amount to dodge the fee. Since 1 January 2026 in the US and Canada, the amount no longer matters for the MAC 03 and 21 rule.
• Retrying insufficient funds every day. Codes 24 to 30 give a time; one retry then beats several before it.
• Losing the MAC in normalisation. If your provider or your own mapping drops the field, you cannot follow it. Store it per attempt, as our guide to building a decline dashboard describes.
• Treating no MAC as permission. An absent or unknown value means no advice, so the response code and network limits still apply.

How does Omno help act on merchant advice codes?

In Omno, cascading is part of the routing rule: if a provider is unavailable or rejects the request, the payment moves to the next provider in the rule until one accepts it, and the provider order is yours to set. The routing-decision log records each attempt and its result, and the dashboard shows decline reasons by provider, method and country. Scheduled renewal retries and dunning messages stay in the merchant’s billing system. The smart routing and cascading page explains the rules.