When a transaction is declined, Merchant Advice Codes (MACs) provide clear guidance on whether and when a retry is appropriate. To support transparency and informed decision-making, Yuno’s public APIs include both normalized and raw response codes. By understanding MACs, merchants can quickly identify the reason for a decline and determine the best actions to take, such as updating routing or customer information before attempting a retry.
MACs list
This table maps Yuno’s normalized Merchant Advice Codes (merchant_advice_code and merchant_advice_code_message) to their equivalents from Mastercard, Visa, and Elo. Use it as a reference to interpret decline reasons, set retry rules, and apply consistent routing strategies across networks.
merchant_advice_code | merchant_advice_code_message | Mastercard | Visa | Elo |
|---|---|---|---|---|
| UPDATE_INFORMATION | Updated/additional information needed | 01 – Updated account information available | – | – |
| TRY_AGAIN_LATER | Retry within 30 days | 02 – Try again later | 3,19,3951,52,5359,60,6162,65,7578,86,9193,96,N3N4,Z5,5C9G | 51,59,0406,38,6162,65,7578,91 |
| DO_NOT_TRY_AGAIN | Do not try again | 03 – Do not try again | 4,7,1214,15,4143,46,57R0,R1,R3 | 57,14,5646,FM,1912,30,1323,41,4364,83,7677 |
| REQUIREMENTS_NOT_FULFILLED | Token requirements not fulfilled | 04 – Token requirements not fulfilled | – | – |
| NO_RETRY_LIFE_CYCLE | No retry life cycle | 21 – Recurring plan cancelled | – | – |
| RETRY_AFTER_1_H | Retry after 1 hours | 24 – Retry after 1 hours (insufficient funds) | – | – |
| RETRY_AFTER_24_H | Retry after 24 hours | 25 – Retry after 24 hours (insufficient funds) | – | – |
| RETRY_AFTER_2_D | Retry after 2 days | 26 – Retry after 2 days (insufficient funds) | – | – |
| RETRY_AFTER_4_D | Retry after 4 days | 27 – Retry after 4 days (insufficient funds) | – | – |
| RETRY_AFTER_6_D | Retry after 6 days | 28 – Retry after 6 days (insufficient funds) | – | – |
| RETRY_AFTER_8_D | Retry after 8 days | 29 – Retry after 8 days (insufficient funds) | – | – |
| RETRY_AFTER_10_D | Retry after 10 days | 30 – Retry after 10 days (insufficient funds) | – | – |
| NO_RETRY_POLICY | No retry policy | 40 – Non-rechargeable prepaid card | – | – |
| NO_RETRY_SECURITY | No retry security | 42 – Sanction score exceeded | – | – |
| MULTIPLE_USE_CARD | Multiple-use virtual card | 43 – Multiple-use virtual card | – | – |
| INVALID_DATA | Incorrect payment information; merchant must revalidate before retry | – | 54,55,82N7,1A,706P | 54,55,8263 |
MAC fields in transactions
Yuno’s public API includes dedicated fields to facilitate the use of Merchant Advice Codes.
Normalized MACs
Yuno provides a standardized set of Merchant Advice Codes that simplify provider responses. These codes let you build retry logic and routing rules without needing to manage every provider’s unique variations.
transactions.merchant_advice_code: A Yuno-normalized MAC returned when a transaction is declined. This code helps you understand the reason for the denial, whether a retry is possible, and what actions to take before reattempting the payment.transactions.merchant_advice_code_message: This fields complements themerchant_advice_codeseen above, providing an explanation of the code in human‑readable terms. This message will allow you to act on the information without having to memorize the meaning of each code.
Raw MACs
Alongside normalized values, Yuno also exposes the original codes and messages returned by providers. These raw fields ensure full transparency and allow you to troubleshoot or follow provider-specific guidance when needed.
transactions.provider_data.merchant_advice_code: The original Merchant Advice Code returned directly from the payment provider. This field gives you access to the raw code for full transparency and troubleshooting.transactions.provider_data.merchant_advice_code_message: A human-readable message from the provider that explains the meaning of the raw MAC. Use this message to understand provider-specific guidance without needing to interpret code values.
Please note these fields are located inside the
transactionsobject in API responses.
About retries
When a card purchase is declined, any subsequent attempt to complete the purchase using the same card is a retry. Fees and thresholds for retries are defined by each card network. How many times you can retry before fees apply varies by brand. Merchants that don’t comply may be charged fees for exceeded transactions.
The payments industry, together with ABECS, standardized response codes for card transaction declines. These attempts are categorized into two types:
- Reversible: A potentially temporary denial that may change over time. The issuer may deny the transaction due to insufficient funds, system issues, or too many unsuccessful PIN attempts.
- Irreversible: Any authorization after an irreversible decline that doesn’t change message fields will fail. This could mean the card has been cancelled or fraud has been confirmed.
Visa, Mastercard, and Elo updated their policies to limit authorization retry attempts after a decline, and they charge fees for attempts beyond those limits. See each brand’s rules below.
Mastercard
Mastercard handles MACs as part of its Transaction Processing Excellence (TPE) program, which has two main components:
Excessive Authorization Attempts
Mastercard’s Excessive Authorization Attempts TPE aims to constantly monitor network utilization to detect and prevent too many authorization requests. Mastercard also monitors approved transactions for very small amounts (less than one unit of currency) that are later refunded, as these can indicate card testing activity.
This monitoring applies to both declined and approved purchases. A retry is defined as any new attempt to authorize a payment using the same card and merchant. Mastercard’s rules set daily and monthly thresholds depending on the region (for example, no more than 10 attempts per day or 35 retries in a month). Exceeding either limit can result in additional fees.
Mastercard Merchant Advice Codes (MACs)
Mastercard uses MACs to help merchants understand when it’s appropriate to retry a transaction. Some declines are irreversible, meaning the transaction should not be retried, often because the card is closed or fraud is confirmed.
The TPE program specifically tracks retries after these irreversible declines, focusing on two codes: MAC 03 (“Do not try again”) and MAC 21 (“No retry life cycle”). If you try to process the same card and amount again after receiving one of these codes, Mastercard may charge you a fee.
Other MACs, such as those indicating a temporary issue or insufficient funds, don’t trigger MAC Transaction Excellence fees, but you could still be charged under the Excessive Authorization Attempts program if you exceed retry limits.
In some cases, MACs will recommend waiting a specific amount of time before retrying (for example, “Retry after 24 hours”). These help you choose the best moment to try again.
View all Mastercard MACs and their Yuno-normalized equivalents in the MACs list.
Visa
Visa's MACs are organized in four categories. The goal is to keep the ecosystem balanced, reduce unnecessary retries, and require issuers to use precise, non‑generic decline codes.
Visa FeesSince they are irreversible, category 1 codes incur a charge from the 2nd attempt. Categories 2, 3, and 4 allow up to 20 attempts within 30 days, with fees starting from the 21st attempt. After 30 days from the first attempt, any retry is charged. Visa's fees are as follows:
- Domestic: USD 0.10 + 13.83% tax
- Cross border: USD 0.25 + 13.83% tax
Category 1 (issuer will never approve)
Irreversible, signals the card was canceled or never existed, or that the denial is the result of a permanent restriction or error that will block future approval. Fees from the second attempt.
- Common category 1 codes may include:
04,07,12,15,41,43,46,57,R0,R1,R3
Category 2 (issuer cannot approve at this time)
Reversible, means the denial results from a temporary condition such as credit risk or other card restrictions that may allow a retry of the transaction to be approved. Some cases require action by the cardholder or issuer to remove the restriction before approval.
- Common category 2 codes may include:
03,19,39,51,52,53,59,61,62,65,75,78,86,91,93,96,N3,N4,Z5,5C,9G
Category 3 (data quality)
Reversible, is triggered by a data error identified by the issuer. Merchants must revalidate payment data before retrying. These denial codes may signal potential fraud risks to merchants.
- Common category 3 codes may include:
14,54,55,70,82,1A,6P,N7
Category 3 ChargesMerchants can have up to 25,000 declined transactions with data quality errors (category 3) in a 30-day period. If you go over this limit, Visa will charge a fee for every additional declined transaction in this category.
Category 4 (generic response codes)
Reversible, includes all other decline response codes not in categories 1, 2, and 3, as there may be cases where there is no response code value for a specific decline. Issuers may use other response code values defined in the VisaNet Technical Specifications. However, minimal use is advised.
All Visa MACs and their Yuno-normalized equivalents are available in the MACs list.
Elo
Elo implemented rules in January 2025, aiming to reduce unnecessary retries by merchants and acquirers. Transactions are counted from the 1st to the last calendar day of the month.
Elo FeesBRL 0.80 per attempt that exceeds the group limit.
Elo groups and retry rules
Elo classifies reversible and irreversible codes into three separate groups:
| Group | Description | Charge rule |
|---|---|---|
| Group 1 (Irreversible) | Transactions denied with irreversible codes (same card, same establishment CNPJ, same amount) | Charged from the 2nd attempt within the month of assessment |
| Group 2 (Reversible) | Transactions declined with reversible codes | Charged from the 16th attempt within the month of assessment |
| Group 3 (Data quality) | Declines with characteristics of brute‑force attacks (considering the same merchant Root CNPJ) | Charged from 10,001 denied transactions if >5% of total refusals |
“CNPJ” refers to the Brazilian business taxpayer identification for the establishment (Root CNPJ at the group level).
Refer to the for all Elo MACs listand Yuno-normalized equivalents.
Other brands
- Reversible codes: Retry attempts are allowed for the same customer and card. There is no limit or pre-established time limit.
AttentionBefore attempting again, follow the guidance received in the denied transaction response.
- Irreversible Codes: Authorizations for the same card or establishment will not be allowed after receiving the first refusal response from the issuer.
Routing with MAC
Retry behavior should be implemented via routing conditions. Update routes to include the new MAC conditions.
When creating a decline group in the Yuno dashboard, you can choose to add conditions by Response Code or by MAC Code.
Transition PeriodUntil all integrations emit MAC separately, some MAC values will appear under both Response Codes and MAC Codes. This is expected while the feature's rollout completes.
