Merchant Advice Code (MAC)

When Mastercard returns an issuer decline result, it will attach a Merchant Advice Code (MAC). Different from the Issuer Response Code, MAC does not explain the specific cause of transaction failures. Instead, it delivers explicit guidance on whether retries are allowed and the recommended retry timeline. This helps you optimize retry strategies, improve subsequent authorization success rates, and prevent penalties imposed by card organizations due to invalid retries.

MAC is returned together with the issuer response code and error message. You may query this value via the merchantAdviceCode field after payment failures. If you need to obtain this field within API responses, please contact PayerMax Technical Support for integration guidelines.

Note

MAC is only applicable to Mastercard transactions. However, not all Mastercard issuers support returning MAC values, which means this field may be missing in some scenarios. Under such circumstances, you shall take the issuer response code and error message as the primary judgment criteria.

Merchant Advice Code (MAC)	Advice Code Description	Definition	Remark (Recommended Handling Actions)
01	New account information available	There has been a change in the shopper's account information, for example a new expiry date for an expired card.	The cardholder’s account details have been updated (e.g., renewed card expiry date). You are advised to retrieve the latest card information through the Account Updater service or confirm details directly with the cardholder.
02	Cannot approve at this time, try again later	This can happen because of a credit limit, or insufficient funds on the card.	The transaction was rejected due to credit limit exhaustion or insufficient account balance. Retry the transaction after 72 hours as recommended.
03	Do not try again	The account is closed, or the issuer suspects fraud.	The account has been closed or flagged for potential fraud by the issuer. Do not initiate further retries for this card; repeated retries may trigger excessive retry penalties from Mastercard. It is recommended to ask the cardholder to switch to another payment method.
04	Token requirements not fulfilled for this token type	There is a technical issue related to the token used in this payment.	Technical defects exist in the token applied for this transaction. Please contact PayerMax Technical Support for troubleshooting assistance.
21	Payment cancellation	The shopper has canceled the recurring payment agreement with their issuer.	The cardholder has terminated the recurring billing agreement on the issuer side. Do not retry against this billing agreement, and confirm follow-up solutions with the cardholder.
24	Retry after 1 hour	Insufficient funds on the shopper's account.	Insufficient account balance. Retry the transaction after 1 hour as recommended.
25	Retry after 24 hours	Insufficient funds on the shopper's account.	Insufficient account balance. Retry the transaction after 24 hours as recommended.
26	Retry after 2 days	Insufficient funds on the shopper's account.	Insufficient account balance. Retry the transaction after 2 days as recommended.
27	Retry after 4 days	Insufficient funds on the shopper's account.	Insufficient account balance. Retry the transaction after 4 days as recommended.
28	Retry after 6 days	Insufficient funds on the shopper's account.	Insufficient account balance. Retry the transaction after 6 days as recommended.
29	Retry after 8 days	Insufficient funds on the shopper's account.	Insufficient account balance. Retry the transaction after 8 days as recommended.
30	Retry after 10 days	Insufficient funds on the shopper's account.	Insufficient account balance. Retry the transaction after 10 days; if the payment still fails, guide the cardholder to use an alternative payment method.
40	Consumer non-reloadable prepaid card	The card is a non-reloadable (single-load) consumer prepaid card.	This is a non-reloadable consumer prepaid card whose balance cannot be topped up normally. Guide the cardholder to select other payment options.
41	Consumer single-use virtual card number	The card is a single-use virtual card number, only valid for one transaction.	This one-time virtual card number is only valid for a single transaction. You cannot retry payments with the same card number upon failure; advise the cardholder to apply for a new payment credential.
42	Sanctions Scoring Service	The transaction was flagged by Mastercard's sanctions screening service.	The transaction has been intercepted by Mastercard sanctions list screening service. Retries are not suggested; verify the cardholder identity and transaction background in accordance with your internal compliance procedures.
43	Consumer multi-use virtual card number	Transaction was carried out with a consumer multi-use virtual card number.	This reusable consumer virtual card number requires no special handling. You may refer to corresponding issuer response codes to implement standard retry logic.

FAQs

Q: Is it necessary to refer to Issuer Response Codes even when MAC data is received?

Yes. MAC serves as supplementary information for Issuer Response Codes, and the two should be used in combination. Issuer Response Codes indicate the root cause of transaction failures, while MAC defines subsequent handling rules (whether retries are permitted and the appropriate retry window).

Q: What does it mean if a transaction returns no MAC value?

It means the issuing bank does not provide this advisory code, mostly because the issuer has not enabled MAC return functionality. In such cases, you must judge transaction issues primarily based on Issuer Response Codes and error messages.

Q: Will transactions processed via Visa / JCB / Diners / Discover card networks return MAC values?

No. MAC is an exclusive field designed for Mastercard, and equivalent mechanisms are not available on other card networks. If you need to build retry policies for Visa and other card scheme transactions, formulate your own retry rules directly based on the Issuer Response Code.