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
• (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 MasterCard Payment Gateway provides 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.summaryStatus: a summarized response indicating the overall card enrollment status
• response.3DSecure.gatewayCode: a detailed response describing the card enrollment status

You should look at 3DSecure.summaryStatus to determine the next step to take.  This is summarized in the table below:

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

If the card is enrolled (response.3DSecure.gatewayCode = CARD_ENROLLED), 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 MasterCard Payment Gateway provides the results of the authentication in the response:

• 3DSecure.summaryStatus: a summarized response indicating the overall authentication status
• response.3DSecure.gatewayCode: a detailed response describing the authentication status

You should look at response.3DSecure.summaryStatus to determine the next step to take.  This is summarized in the table below:

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 MasterCard Payment Gateway will use the 3DSecureId to look up the authentication results that it stored when you asked it to process the authentication result. the MasterCard Payment 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 HTM 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 3DSecure parameter group of the Pay or Authorize operation.

There is one mandatory field:

• 3DSecure.enrollmentStatus: indicates if the cardholder is enrolled for 3DS. This field is mandatory.

Other 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:

• 3DSecure.authenticationStatus: indicates if 3DS authentication of the payer was successful.
• 3DSecure.authenticationToken: The base64 encoded value generated by the card issuer that may be returned to you in the authentication response message.
• 3DSecure.acsEci: the Electronic Commerce Indicator that may be returned to you in the authentication response message.
• 3DSecure.xid: a unique transaction identifier for the 3DS authentication.

Preauthenticated 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 MasterCard Payment Gateway provides a summary of the authentication status in the response.3DSecure.gatewayCode field. If you want to derive the values for the 3DS fields used to process a payment, you can do this from the response.3DSecure.gatewayCode field.

If required, you can derive the VERes.enrolled value from 3DSecure.enrollmentStatus:

You may also derive the PAREs.status value from 3DSecure.authenticationStatus:

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 Payment Authentication Search option in Merchant Administration.

The Authentication State code shown when viewing authentication details in Merchant Administration can be mapped to response.3DSecure.gatewayCode. See New Codes in the table below:

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.authenticationStatus).

Testing is supported for the following 3D-Secure Authentication schemes:

• Mastercard SecureCode
• Verified by Visa
• American Express SafeKey
• J/Secure
• Diners ProtectBuy

To test the 3D-Secure Authentication functionality:

1. Use a 3D-Secure Enrolled test card (see cards listed in the specific Acquirer sections) when submitting the CHECK_3DS_ENROLLMENT request for your Test Merchant Profile.
2. Check that you receive a response with response.3DSecure.gatewayCode=CARD_ENROLLED.
3. Use the form provided in 3DSecure.authenticationRedirect.simple.htmlBodyContent to redirect the payer's browser to the ACS Emulator page.

   The ACS Emulator redirects the payer's browser back to your website and contains the PARes.

4. Submit a PROCESS_ACS_RESULT request with the PARes in 3DSecure.paRes.
5. Use the ID for this 3D-Secure Authentication via the MasterCard Payment Gateway provided in 3DSecureId in a subsequent transaction request (e.g. PAY or AUTHORIZE).