Merchant Advice Codes (MAC)

A Merchant Advice Code (MAC) is a standardized code the card network returns with a declined authorization. It tells you why the payment was declined and whether, and when, you can retry.

Following the MAC protects your approval rates. Retrying a card that the issuer told you not to retry raises network fees, lowers authorization rates and can lead to compliance penalties.

When is the MAC available?

PPRO returns the MAC when the card network or acquirer provides one.

Only on declines. It appears inside failure.additionalData on a failed payment. Successful payments do not include it.
Not on every decline. It is optional. Handle declines that have no MAC with your standard retry logic and failure.isRetryable.
Depends on network and acquirer. Availability varies by card network, acquirer and market.
Not only on authorizations. The same additionalData structure appears in failures on captures, voids, refunds and payment agreements.
Most relevant for stored cards. It matters most for merchant-initiated payments. See Card on File.

Field	Type	Description
`failure.additionalData.merchantAdviceCode`	string	The MAC returned by the network, for example `"01"`.
`failure.additionalData.merchantAdviceCodeText`	string	Human-readable explanation. Use it for logs and support tools. Base your logic on the code, not on the text.

Example response

{
  "id": "charge_aPWseusjHRt144BTwXdU2",
  "status": "FAILED",
  "failure": {
    "failureType": "PROVIDER_DECLINE",
    "failureCode": "INSUFFICIENT_FUNDS",
    "providerFailureCode": "51",
    "failureMessage": "Insufficient funds",
    "isRetryable": true,
    "additionalData": {
      "merchantAdviceCode": "25",
      "merchantAdviceCodeText": "Retry after 24 hours"
    }
  }
}

Values and recommended actions

Groups at a glance

Group	Codes	What to do
Get new card details	`01`	Do not retry the current card. Refresh the credentials.
Retry later	`02`, `24` to `30`	Retry after the waiting period.
Do not retry	`03`, `21`, `40`, `41`	Stop. Ask for a new payment method.
Fix integration	`04`	Network tokenization requirements are not met.
Informational	`43`	Normal rules apply.

Full reference

MAC	Meaning	Recommended action
`01`	New account information available	Do not retry the current card. Check Account Updater for new details, or ask the customer to update their payment method.
`02`	Cannot approve at this time, try again later	Retry later, following your normal dunning schedule (for example after 24 to 48 hours).
`03`	Do not try again	Stop all retries. The account is closed, frozen or flagged for fraud. Remove the card from your billing cycle and ask for a new payment method.
`04`	Token not supported	Do not retry with the same credential. Network tokenization requirements are not fulfilled. Review your tokenization setup.
`21`	Stop recurring payment	Stop retrying immediately and cancel the recurring plan. The cardholder has canceled the mandate. Further attempts breach scheme rules.
`24`	Retry after 1 hour	Wait at least 1 hour.
`25`	Retry after 24 hours	Wait at least 24 hours.
`26`	Retry after 2 days	Wait at least 2 days.
`27`	Retry after 4 days	Wait at least 4 days.
`28`	Retry after 6 days	Wait at least 6 days.
`29`	Retry after 8 days	Wait at least 8 days.
`30`	Retry after 10 days	Wait at least 10 days.
`40`	Consumer non-reloadable prepaid card	Do not retry. The card cannot support recurring billing. Ask for another payment method.
`41`	Consumer single-use virtual card number	Do not retry. The number cannot be billed again. Ask for a standard payment method.
`43`	Consumer multi-use virtual card number	Informational. Normal recurring rules apply, but the card may expire quickly depending on issuer settings.

🚧
Wait times are minimums
For 24 to 30, retrying earlier than the stated time risks another decline and network penalties.

Handling the MAC in your integration

Read failure.additionalData.merchantAdviceCode on every failed stored-card payment.
Decide the next step from the table above.
When you retry a failed scheduled payment, send initiator: MERCHANT and scheduleType: SCHEDULED_RETRY.
Make sure a retry for a 03 or 21 can never be scheduled automatically.

flowchart TD
    A[Payment FAILED] --> B{merchantAdviceCode<br/>present?}
    B -- No --> C[Use isRetryable and<br/>your standard dunning rules]
    B -- Yes --> D{Code}
    D -- "01" --> E[Do not retry this card.<br/>Wait for Account Updater webhook<br/>or ask customer for new details]
    D -- "02" --> F[Retry later per<br/>dunning schedule]
    D -- "24 to 30" --> G[Retry after the stated<br/>minimum wait<br/>SCHEDULED_RETRY]
    D -- "03, 21, 40, 41" --> H[Stop retries.<br/>Ask for a new payment method]
    D -- "04" --> I[Fix tokenization setup.<br/>Do not retry same credential]
    D -- "43" --> J[Informational.<br/>Normal rules apply]

Best practices

Drive dunning from the code. Map 24 to 30 to exact retry delays in your billing engine.
Never retry 03 or 21. Card networks monitor repeated retries after these codes. Doing so hurts your standing with them and can result in fines.
Log both fields. Keep the code and its text for troubleshooting with support.