Merchant Advice Code (MAC)

The Merchant Advice Code (MAC) is a code returned by Mastercard in declined transactions or other specific scenarios, such as cases involving virtual cards, card data updates (ABU), or token requirements. It complements the transaction return code (ReturnCode) and guides the merchant on which action should be taken:

Retry the transaction;
Wait for a minimum interval;
or do not retry, depending on the scenario identified by the card brand.

In the API response, the MAC is returned in the Payment.MerchantAdviceCode field.

How to interpret the MAC

To interpret the MAC in a declined transaction:

Locate the reason for the decline in the ReturnCode field. Check the ABECS Mastercard table to understand the main reason for the refusal;
Check the Payment.MerchantAdviceCode field;
Consult the Mastercard MAC table to understand the instruction associated with the code.

Follow the instruction in the table exactly, as each MAC code represents a specific instruction.

Return Example

{
  "MerchantOrderId": "2017051001",
  "Customer": {
    "Name": "Aline de Souza",
    "Identity": "12345678909",
    "IdentityType": "CPF",
    "Birthdate": "1990-01-01",
    },
  },
  "Payment": {
    "Installments": 1,
    "Interest": 0,
    "Capture": true,
    "Authenticate": false,
    "Recurrent": false,
    "CreditCard": {
      "CardNumber": "4091688625337641",
      "Holder": "Aline de Souza",
      "ExpirationDate": "12/2035",
      "SaveCard": false,
      "Brand": "Master",
      "CardOnFile": {
        "Usage": "Used",
        "Reason": "Unscheduled"
      },
      "PaymentAccountReference": "ZEYO5L521MBLKDQU0HHXENP1B1B58"
    },
    "Tid": "1209032335683",
    "ProofOfSale": "255231",
    "AuthorizationCode": "875176",
    "SoftDescriptor": "LojaTeste",
    "Provider": "Simulado",
    "InitiatedTransactionIndicator": {
      "Category": "C1",
      "Subcategory": "StandingOrder"
    },
    "SentOrderId": "202512091523357AF3AB",
    "Amount": 10000,
    "ReceivedDate": "2025-12-09 15:23:35",
    "CapturedAmount": 10000,
    "CapturedDate": "2025-12-09 15:23:35",
    "Status": 3,
    "IsSplitted": false,
    "ReturnCode": "51",
    "ReturnMessage": "Autorização negada",
    "MerchantAdviceCode": "25",
    "PaymentId": "71c908df-c72d-425c-89d2-3376f1b5a76d",
    "Type": "CreditCard",
    "Currency": "BRL",
    "Country": "BRA",
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/71c908df-c72d-425c-89d2-3376f1b5a76d"
      },
      {
        "Method": "PUT",
        "Rel": "void",
        "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/71c908df-c72d-425c-89d2-3376f1b5a76d/void"
      }
    ]
  }
}

{
  "MerchantOrderId": "202301131052",
  "Customer": {
    "Name": "Aline de Souza",
    "Identity": "12345678909",
    "IdentityType": "CPF",
    "Birthdate": "1990-01-01",
    },
  "Payment": {
    "DebitCard": {
      "CardNumber": "4091688625337641",
      "Holder": "Aline De Souza",
      "ExpirationDate": "12/2035",
      "SaveCard": false,
      "Brand": "Master",
      "PaymentAccountReference": "9UAPP3YTRG9ICN42TM09I8TH83116"
    },
    "AuthorizationCode": "539727",
    "ProofOfSale": "603679",
    "Authenticate": true,
    "Recurrent": false,
    "SentOrderId": "202301131052",
    "Amount": 0,
    "ReceivedDate": "2026-03-02 16:09:32",
    "CapturedAmount": 0,
    "CapturedDate": "2026-03-02 16:09:32",
    "Status": 3,
    "IsSplitted": false,
    "ReturnCode": "51",
    "ReturnMessage": "Autorização negada",
    "MerchantAdviceCode": "25",
    "PaymentId": "f898786f-4377-4d9f-b73d-7a336ecf0edf",
    "Type": "DebitCard",
    "Currency": "BRL",
    "Country": "BRA",
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/f898786f-4377-4d9f-b73d-7a336ecf0edf"
      }
    ]
  }
}