For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

Message Extension

Use this field to send customized information to the card issuer

In the 3D Secure 2 protocol, the Message Extension fields allow for more customized and card-specific information to be passed in both the request and response messages. This article focuses on what Mastercard uses the Message Extension fields for, including:

Strong Customer Authentication (SCA) exemptions and Allowlisting
Merchant fraud rate
Acquirer country code
Secure corporate payments

To get the most out of this article, we recommend you first read our Browser Authentication for 3D Secure article.

SCA exemptions

One of the key advantages of 3D Secure 2 is that it provides a framework for merchants to benefit from exemptions from SCA under certain conditions. With 3D Secure version 2.2, merchants can flag specific exemptions using the Challenge Request Indicator field.

In addition, for Mastercard authentications, the specific exemption the merchant is requesting must be included in the Message Extension fields during the Initiate Authentication step.

Sample request (specific fields)

In the authentication request, include the following fields.

"challenge_request_indicator":"NO_CHALLENGE_REQUESTED",
"message_extension": [
   {
      "name": "Merchant Data",
      "id": "A000000004-merchantData",
      "criticality_indicator": "false",
      "data": {
         "A000000004-merchantData": {
            "scaExemptions":"05"
         }
      }
   }
]

Request Syntax (Specific Fields)

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field or regional requirement.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Description
Challenge Request Indicator	string	enum	Indicates whether a challenge is requested for this transaction. The Issuer may override whatever preference is specified in this field. In this use case it should always be set to the following: NO_CHALLENGE_REQUESTED - Preference is for the customer not to be challenged. European merchants: optional for SCA.
Message Extension Name	string	alphanumeric	The name of the extension data set as defined by the extension owner. Maximum 64 characters.
Message Extension ID	string	alphanumeric	A unique identifier for the extension. Maximum 64 characters.
Message Extension Criticality Indicator	boolean		Indicates whether the data in the Message Extension affects the overall response. True - The message is critical. The overall response can only be understood by taking into account the extension data. False - The message is non-critical. The overall response message is not affected by the extension data and can be interpreted as normal. Under normal circumstances the Criticality Indicator will return as false.
Message Extension Data	string	alphanumeric	The data carried in the extension. Maximum 8059 characters.
SCA Exemptions	string	numeric	Used to indicate SCA exemption request for all types of possible SCA exemptions (see list below). 05 - No challenge requested (transactional risk analysis is already performed) 06 - No challenge requested (data share only) 07 - No challenge requested (strong costumer authentication already performed) Allowed values: 05, 06, 07

Sample response (specific fields)

If the request for an exemption is successful, the response of the Authentication request will contain the following values. The authentication value will start with kN.

{
   "authentication_value": "kNABBhIBRwAAAAAANQFHAAAAAAA=",
   "status": "AUTHENTICATION_FAILED",
   "status_reason": "81",
   "eci": "06",
}

Response Syntax (specific fields)

Element/Field	Category	Format	Description
Authentication Value	string	alphanumeric	Unique value provided as part of the ACS registration for each supported DS. Must be used to provide proof of authentication. In this case, if the exemption request is successful the leading indication of this value will be kN.
Transaction Status	string	enum	Indicates whether a transaction qualifies as an authenticated transaction or account verification. In this case, if the exemption request is successful the value will be AUTHENTICATION_FAILED
Transaction Status Reason	string	enum	Indicates whether a transaction qualifies as an authenticated transaction or account verification. In this case, if the exemption request is successful the value will be: 81 which for Mastercard maps to Challenge Exemption Accepted.
Eci	string	alphanumeric	The E-Commerce Indicator: indicates whether chargeback protection is available for the transaction or not.

Allowlisting

3D Secure 2 allows customers to allowlist, or whitelist, certain merchants—effectively telling the Issuer that transactions with particular merchants should be trusted. If this occurs, the Issuer may return information in the authentication response regarding the allowlist status of the merchant.

In version 2.1, Mastercard does not support allowlisting merchants as trusted beneficiaries list. However, Mastercard is able to share the allowlist status of a merchant through message extension.

Sample response (specific values)

"message_extension": [
   {
      "name": "ACS Data",
      "id": "A000000004-acsData",
      "criticality_indicator": "false",
      "data": {
         "A000000004-acsData": {
            "whitelistStatus":"Y"
         }
      }
   }
],

Response syntax (specific fields)

Element/Field	Category	Format	Description
Message Extension Name	string	alphanumeric	The name of the extension data set as defined by the extension owner. Maximum 64 characters.
Message Extension ID	string	alphanumeric	A unique identifier for the extension. Maximum 64 characters.
Message Extension Criticality Indicator	boolean		Indicates whether the data in the Message Extension affects the overall response. True - The message is critical. The overall response can only be understood by taking into account the extension data. False - The message is non-critical. The overall response message is not affected by the extension data and can be interpreted as normal. Under normal circumstances the Criticality Indicator will return as false.
Message Extension Data	string	alphanumeric	The data carried in the extension. Maximum 8059 characters.
SCA Exemptions	string	string	Indicates the whitelist status of the merchant with the customer. Y - Merchant is whitelisted by customer N - Merchant is not whitelisted by customer E - Not eligible as determined by Issuer P - Pending confirmation by customer R Customer Rejected U - Whitelist status unknown, unavailable, or does not apply

Merchant fraud rate

Mastercard allows the merchant fraud rate to be shared with the Issuer as part of the Authentication Request message using a specific Message Extension field. Sharing the merchant fraud rate can increase the Issuer’s level of confidence in the transaction. Issuers can also use it to decide if a merchant should be eligible for the allowlist exemption.

There is no change to the response message when using this extension.

Sample request (specific fields)

In the authentication request, include the following fields.

"message_extension": [
   {
      "name": "Merchant Data",
      "id": "A000000004-merchantData",
      "criticality_indicator": false,
      "data": {
         "A000000004-merchant_data":{
         "merchantfraudrate": "1"
         }
      }
   }
]

Request syntax (specific fields)

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field or regional requirement.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Description
Message Extension Name	string	alphanumeric	The name of the extension data set as defined by the extension owner. Maximum 64 characters.
Message Extension ID	string	alphanumeric	A unique identifier for the extension. Maximum 64 characters.
Message Extension Criticality Indicator	boolean		Indicates whether the data in the Message Extension affects the overall response. True - The message is critical. The overall response can only be understood by taking into account the extension data. False - The message is non-critical. The overall response message is not affected by the extension data and can be interpreted as normal. Under normal circumstances the Criticality Indicator will return as false.
Message Extension Data	string	alphanumeric	The data carried in the extension. Maximum 8059 characters.
Merchant Fraud Rate	string	string	Indicates the Merchant fraud rate in bps taking into account all Merchant sites and card volumes. Calculated as per PSD2 RTS Article 19 1 - (represents fraud rate ≤1) 2 - (represents fraud rate 1+ - 6) 3 - (represents fraud rate 6+ -13) 4 - (represents fraud rate 13+ -25) 5 - (represents fraud rate >25)

Acquirer country code

Merchants can use this extension to inform the Issuer if the Acquirer country and merchant country differ. This is particularly important for transaction processing in countries where regulations may apply based on the Acquirer country.

If a transaction is “two-leg” — that is, the country code of both the Acquirer and the Issuer is in the European Economic Area (EEA) — then it is in scope of SCA. It is therefore important to share the Acquirer country code; otherwise, an Issuer could incorrectly flag a transaction as a “one-leg” transaction, which would be out of scope of SCA.

There is no change to the response message when using this extension.

Sample request (specific fields)

In the authentication request, include the following fields.

"message_extension": [
   {
      "name": "Merchant Data",
      "id": "A000000004-merchantData",
      "criticality_indicator": false,
      "data": {
         "A000000004-merchant_data":{
         "acquirer_country_code": "050"
         }
      }
   }
]

Request syntax (specific fields)

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field or regional requirement.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Description
Message Extension Name	string	alphanumeric	The name of the extension data set as defined by the extension owner. Maximum 64 characters.
Message Extension ID	string	alphanumeric	A unique identifier for the extension. Maximum 64 characters.
Message Extension Criticality Indicator	boolean		Indicates whether the data in the Message Extension affects the overall response. True - The message is critical. The overall response can only be understood by taking into account the extension data. False - The message is non-critical. The overall response message is not affected by the extension data and can be interpreted as normal. Under normal circumstances the Criticality Indicator will return as false.
Message Extension Data	string	alphanumeric	The data carried in the extension. Maximum 8059 characters.
Acquirer Country Code	string	string	ISO 3166-1 numeric three-digit country code

Policies

Connect

Additional Resources

Message Extension

SCA exemptions

Sample request (specific fields)

Request Syntax (Specific Fields)

Sample response (specific fields)

Response Syntax (specific fields)

Allowlisting

Sample response (specific values)

Response syntax (specific fields)

Merchant fraud rate

Sample request (specific fields)

Request syntax (specific fields)

Acquirer country code

Sample request (specific fields)

Request syntax (specific fields)