Mastercard Merchant Advice Codes (MACs)

Every Mastercard decline includes a two-digit response code in Field 39 of the ISO 8583 message. That code tells you what happened. The Merchant Advice Code tells you what to do about it.

Response codes were designed in the 1980s and carry decades of ambiguity. Code 05, for instance, could mean suspected fraud, a temporary hold, or an issuer system glitch. The MAC system, introduced by Mastercard to sit alongside these codes, provides explicit, machine-readable instructions from the issuer. Think of it as the issuer saying: "I declined this, and here is exactly how you should handle the next attempt."

MACs 24 through 30 are timed retry codes. The issuer is telling you, in plain terms, when to try again: 1 hour, 24 hours, 2 days, 4 days, 6 days, 8 days, or 10 days. Most billing systems ignore these entirely and fall back to fixed retry schedules (e.g., days 1, 3, 5, 7).

This is leaving money on the table. If an issuer returns MAC 24 (retry after 1 hour), your fixed 24-hour retry delay means you are waiting 23 hours longer than necessary. If they return MAC 27 (retry after 4 days) and you retry after 1 day, you will get declined again and burn one of your limited retry attempts for nothing.

The fix is straightforward: parse the MAC, and if it falls in the 24-30 range, override your default retry schedule with the issuer-specified window. This single change can measurably improve recovery rates on Mastercard volume.

MAC 03 means "do not try again." Mastercard enforces this. If you reattempt a transaction that returned MAC 03 within 30 days of the original decline, Mastercard's Transaction Processing Excellence (TPE) program treats each subsequent attempt as an excess retry.

As of January 2025, the fee is $0.50 per excess attempt on MAC 03 violations. For a subscription business processing thousands of recurring payments, ignoring MAC 03 can generate substantial penalty fees. Mastercard also tracks your violation rate at the merchant level, and chronic violators face escalating consequences including mandatory action plans.

The implementation is simple: when you receive MAC 03, mark that payment method as non-retriable for at least 30 days. If the customer wants to continue their subscription, they need to provide a new card.

Stripe added the network_advice_code field to the Charge object in December 2024 with API version 2024-12-18.acacia. You can find it at:

charge.payment_method_details.card.network_advice_code

This field is only populated on Mastercard declines. For Visa, use network_decline_code combined with Visa's category system (see the Visa Decline Categories guide).

To access it, ensure your Stripe API version is 2024-12-18.acacia or later. If you are on an older version, you can pin the newer version in individual API calls without upgrading your entire integration:

Stripe::Charge.retrieve(charge_id, {}, { api_version: '2024-12-18.acacia' })

The field returns the two-digit MAC value as a string: "01", "03", "24", etc.

Mastercard's Transaction Processing Excellence (TPE) program monitors merchants for excessive reattempts on declined transactions. MACs are the primary signal Mastercard uses to determine whether a retry is legitimate or excessive.

TPE tracks two key metrics:

• Reattempt rate: The percentage of declined transactions that are retried within 30 days.
• Reattempt violation rate: The percentage of retries that violate MAC guidance (e.g., retrying a MAC 03 decline, or retrying before a MAC 25's 24-hour window has elapsed).

Merchants exceeding TPE thresholds receive notifications from their acquirer with a remediation timeline. Continued violations result in per-transaction fees and, in severe cases, restrictions on retry privileges.

The practical takeaway: build your retry logic around MACs, not around arbitrary schedules. If you honor MAC 03 as a hard stop, respect MAC 24-30 retry windows, and use MAC 01 to trigger Account Updater queries, you will stay well within TPE compliance and recover more revenue in the process.