3-D Secure Authentication

You can check whether a card is enrolled by providing the following fields in the Check 3DS Enrollment request:

• 3DSecureId: your unique identifier for this authentication.  You should include this same identifier in all subsequent operations.
• 3DSecure.authenticationRedirect.responseUrl: the URL you want to redirect the payer to after completing the 3DS authentication process
• order.amount: the total amount of the order
• order.currency: the currency of the order
• sourceOfFunds.provided.card.* or session.id or sourceOfFunds.token: details of the card being used for the payment.

  Network Tokens

  The gateway can process network tokens in the Check 3DS Enrollment request. Network tokens obtained from Mastercard Digital Enablement Service (MDES) and Visa Token Service (VTS) tokenization service providers are currently supported.

  If you have obtained a network token by integrating directly to the network tokenization service then you must supply token details using the following fields (MDES tokens supported from API v54 onwards, and VTS tokens supported from API v55 onwards):

  • sourceOfFunds.type=SCHEME_TOKEN: Enables the gateway to identify the source of fund provided in the request as a network token.
  • sourceOfFunds.provided.card.number: The network token. Supply the value for the MDES "Token PAN" or the VTS "Token".
  • sourceOfFunds.provided.card.expiry: (optional) The network token expiry.

  If you have been enabled for network tokenization by your payment service provider, any request to the gateway for a gateway token will also attempt to generate a corresponding network token. The gateway will also attempt network tokenization for any applicable cards already stored in the gateway token repository. The Check 3DS Enrollment request will use the network token if available else the Funding PAN (FPAN) stored against the gateway token will be used (MDES tokens supported from API v55 onwards, and VTS tokens supported from API v56 onwards).

• (Optional) 3DSecure.goodsDescription: you may provide a brief description of the goods being purchased. If supported by the issuer’s Access Control Server (ACS), this description will be displayed on the authentication page presented to the payer.

The gateway returns the results of the enrollment check in the response:

• 3DSecure.xid: a unique transaction identifier generated by the MasterCard Payment Gateway for the 3DS authentication.
• 3DSecure.veResEnrolled: indicates if payer authentication is available for the card number.

The gateway also returns response.gatewayRecommendation, which you can use to determine the next step. This recommendation is based on the 3DS transaction filtering rules configured by you or your payment service provider.

For an advanced integration, you can determine the next step using the value returned in the 3DSecure.veResEnrolled field. This is summarized in the table below. Refer to the card scheme documentation to interpret the "enrolled" field in the Verify Enrollment Response (VERes) message.

Check 3DS Enrollment API Reference [REST] [NVP]

If the card is enrolled, (for example, 3DSecure.veResEnrolled = Y), then you should redirect the payer's browser to the card issuer's website for authentication. Simply return the content provided in the 3DSecure.authenticationRedirect.simple.htmlBodyContent to the payer's browser.

When the authentication process at the card issuer's website is complete, the issuer's Access Control Server (ACS) returns the authentication response to you in the form of a HTTP post to the response URL (3DSecure.authenticationRedirect.responseUrl) you specified in the Check 3DS Enrollment request.

The Payment Authentication Response (PARes) returned to you is provided as a base64 encoded value. To decode this value, transfer the PARes to the 3DSecure.paRes field on the Process ACS Result operation and submit the operation. The gateway provides the results of the authentication in the response:

• 3DSecure.veResEnrolled: indicates if payer authentication is available for the card number.
• 3DSecure.paResStatus: indicates the result of payer authentication with the issuer. This field is not returned if the PaRes is invalid. Refer to the relevant card scheme documentation to determine the next step.

The gateway also returns response.gatewayRecommendation, which you can use to determine the next step. Please note that this recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.

For an advanced integration, you can determine the next step using the value returned in the 3DSecure.paResStatus field. This is summarized in the table below. Refer to the card scheme documentation to interpret the "status" field in the PARes message.

Process ACS Result API Reference [REST] [NVP]

When the result of the Check 3DS Enrollment or Process ACS operation indicates that you can proceed with the payment, you may initiate an Authorize or Pay operation. Include the 3DSecureId that you supplied in the Check 3DS Enrollment operation in the request. You do not need to include any of the parameters in the 3DSecure parameter group, as the gateway will use the 3DSecureId to look up the authentication results that it stored when you asked it to process the authentication result. The gateway will pass the required information to the acquirer.

3DSecureId on Authorize API Reference [REST] [NVP]

3DSecureId on Pay API Reference [REST] [NVP]

Before checking 3DS enrollment, you can submit a rate quote request for dynamic currency conversion (DCC) to retrieve the payer's currency and the order amount in that currency. If the payer accepts the DCC offer, you must then include the DCC information in the check 3DS enrollment request.

DCC on Check 3DS Enrollment API Reference [REST] [NVP]

The HTML required for the form used to redirect the payer for authentication may be generated using one of two page generation methods:

1. Simple: the MasterCard Payment Gateway generates the HTML form. The complete form is returned in the Check 3DS Enrollment response. This is the default option.
2. Customized: you will generate your own customized HTML form using the parameters provided in the Check 3DS Enrollment response.

The response to the Check 3DS Enrollment operation will include the information required for the selected option.

(Optional) Customize the Simple Form

You may tailor the simple form generated by setting 3DSecure.authenticationRedirect.pageGenerationMode = SIMPLE in the Check 3DS Enrollment request, and then specifying values for one or more parameters:

• 3DSecure.authenticationRedirect.simple.expectedHtmlEncoding
• 3DSecure.authenticationRedirect.simple.redirectDisplayBackgroundColor
• 3DSecure.authenticationRedirect.simple.redirectDisplayContinueButtonText
• 3DSecure.authenticationRedirect.simple.redirectDisplayTitle

(Optional) Generate your Own Customized Form

You may specify that you will generate your own form by setting 3DSecure.authenticationRedirect.pageGenerationMode = CUSTOMIZED in the Check 3DS Enrollment request.  The response will include the following parameters:

• 3DSecure.authenticationRedirect.customized.acsUrl: the URL of the issuer's Access Control Server (ACS) where the payer can be authenticated.
• 3DSecure.authenticationRedirect.customized.paReq: the Payer Authentication Request (PAReq) message to send to the ACS to initiate payer authentication.

Include these values in your form, along with the URL to return the payer to once the authentication is complete.

A sample customized form is shown below.

    
  <!-- Populate the form action attribute with the value returned in the 3DSecure.authenticationRedirect.customized.acsUrl response parameter -->

  <form name="3dsRedirect" action="[3DSecure.authenticationRedirect.customized.acsUrl]" method="POST" accept-charset="UTF-8">
 
  <!-- Populate the mandatory PaReq parameter with the value returned in the 3DSecure.authenticationRedirect.customized.paReq response parameter.  -->

  <input type="hidden" name="PaReq" value="[3DSecure.authenticationRedirect.customized.paReq]"/> 
 
  <!-- Populate the mandatory TermUrl value with the URL to which you want the payer returned when the authentication process has completed. This should be the same value as supplied in the 3DSecure.authenticationRedirect.responseUrl  parameter to the CHECK_ENROLLMENT request. -->
 
  <input type="hidden" name="TermUrl" value="https://merchant.com/3ds/return"/>

  <!-- The ACS will echo the contents of the mandatory MD parameter when the payer is returned to the URL specified in the TermUrl parameter.  You can use this parameter to establish a link between the ACS request and response. -->

  <input type="hidden" name="MD" value="[mdvalue]"/> 

  <input type="submit" value="Click  here to continue" class="button">

  </form>
  

Customize Form on Check 3DS Enrollment API Reference [REST] [NVP]

If you have used an external 3DS MPI to authenticate the payer, then you must pass information about the authentication in the authentication parameter group of the Pay or Authorize operation.

All fields are optional, as whether or not they were provided to you by the external 3DS MPI depends on the authentication status of the transaction. However, if you have the data it's recommended that you provide it.

• authentication.3ds.acsEci: The Electronic Commerce Indicator that may be returned to you in the authentication response message.
• authentication.3ds.authenticationToken: The base64 encoded value generated by the card issuer that may be returned to you in the authentication response message.
• authentication.3ds.transactionId: A unique transaction identifier generated by the gateway for the 3DS authentication. This field corresponds to XID, which is an identifier generated by the gateway on behalf of the merchant. An XID submitted in this field must be in base64 format.
• authentication.3ds1.paResStatus: Indicates the result of payer authentication with the issuer.
• authentication.3ds1.veResEnrolled: Indicates whether or not payer authentication is available for the card number you provided.

Pre-authenticated 3DS on Authorize API Reference [REST] [NVP]

Preauthenticated 3DS on Pay API Reference [REST] [NVP]

If you wish to retrieve the authentication results at any stage, use the Retrieve 3DS Result operation.

Retrieve 3DS Result API Reference [REST] [NVP]

The gateway provides the enrollment status and the authentication status in the 3DSecure.veResEnrolled and the 3DSecure.paResStatus fields respectively.

VERes is the message returned by the card scheme to the gateway in response to a request to check 3DS enrollment. PARes is the response message returned to the gateway in response to a request for payer authentication.

Refer to the card scheme documentation to interpret the values returned in the 3DSecure.veResEnrolled and 3DSecure.paResStatus fields.

If you submitted 3DS details on a transaction, search for the order or transaction in Merchant Administration. View details of the order, then select the link to view authentication details.

If you want to view authentication details for an authentication for which you did not proceed with the payment (for example, authentication failed), then use the Authentications search option in Merchant Administration.

Yes, you can bypass 3DS authentication for payers where payments are deemed low risk by the external risk provider. For more information, see Dynamic 3DS.

You can test your integration for performing 3DS Authentication via the MasterCard Payment Gateway by using the ACS Emulator. This allows you to select a specific 3DS Authentication result (returned in the transaction response in 3DSecure.paResStatus).