3-D Secure Authentication

3-D Secure Authentication is not applicable to Batch.

3-Domain Secure™ (3-D Secure or 3DS) authentication is designed to protect online purchases against credit card fraud by allowing you to authenticate the payer before submitting an Authorization or Pay transaction.  3DS authentication works by redirecting the payer to their card issuer where they enter a previously registered password.

The Mastercard Payment Gateway supports 3DS authentication using  Mastercard SecureCode™, Verified by Visa™, J/Secure™, American Express SafeKey™, and Diners Club ProtectBuy™.

Prerequisites

  • You must be registered with your acquirer to use 3DS
  • You must be enabled for a 3DS scheme on your merchant profile with the Mastercard Payment Gateway.
If "Enforce 3DS for Internet Transactions" privilege is enabled on your merchant profile, you must provide valid 3DS data in the transaction request else the gateway rejects the transaction.

3DS Payer Experience

This section describes a sample checkout flow for your shop site where the payer is authenticated using 3DS.

3-D Secure Authentication Flow

The checkout flow for a successful authentication is as follows:

  1. A payer browses your shop site, selects one or more products, proceeds to the payment page, and selects to pay with a card that supports 3DS.
  2. Check 3DS Enrollment: You ask the Mastercard Payment Gateway to check with the card scheme if the card is enrolled for 3DS
  3. Authenticate Payer: After confirming the card is enrolled, you redirect the payer's browser to their issuer's 3DS authentication page. The payer enters their 3DS password and submits the information. The issuer returns the authentication result to you.
  4. Process ACS Result: You ask the Mastercard Payment Gateway to process the authentication result. Mastercard Payment Gateway provides you with details of the authentication response received from the issuer.
  5. Use the 3DS Result in a Payment Operation: You submit the payment for processing
  6. You display the order confirmation page to the payer.

Integrating to use 3DS Authentication

This section describes how to integrate to the Mastercard Payment Gateway to use 3DS.

Check 3DS Enrollment

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:

3DSecure.summaryStatus Next step
CARD_ENROLLED The card is enrolled for 3DS. Proceed to authenticate the payer.
CARD_NOT_ENROLLED The card is not enrolled for 3DS. Proceed with the payment operation, including the 3DSecureID on the request.
CARD_DOES_NOT SUPPORT_3DS The card does not support 3DS, and you cannot proceed with 3DS authentication.
AUTHENTICATION_NOT_AVAILABLE There was an error. Proceed with the payment operation, including the 3DSecureID on the request

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

Authenticate Payer

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.

This is the default.  You may also choose to customize the form.
Process Authentication Result

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:

3DSecure.summaryStatus Next step
AUTHENTICATION_SUCCESSFUL Authentication of the payer was successful. Proceed with the payment operation, including the 3DSecureID on the request.
AUTHENTICATION_FAILED Authentication of the payer failed. You must not proceed with the payment operation. It is against scheme rules to do so.
AUTHENTICATION_ATTEMPTED Authentication of the payer was attempted but could not be completed. Proceed with the payment operation, including the 3DSecureID on the request.
AUTHENTICATION_NOT_AVAILABLE There was an error. Proceed with the payment operation, including the 3DSecureID on the request

Process ACS Result API Reference [REST] [NVP]

Use the 3DS Result in a Payment Operation

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.

Some authentication results are authentication failures for which a payment should not be processed. In these cases, the Mastercard Payment Gateway will return result = ERROR in the response for the payment operation. You should request another payment method.

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

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

Other Options

Using Dynamic Currency Conversion and 3DS

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]

Customize the Form Used to Redirect the Payer for Authentication

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]

Submit a Pre-Authenticated Payment Operation

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.
Mastercard requires that, if you are using Mastercard SecureCode and 3DSecure.summaryStatus = AUTHENTICATION_ATTEMPTED, you provide 3DSecure.authenticationToken.

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

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

Retrieve 3DS Authentication Results

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

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

FAQs

How do I determine the enrollment status and the authentication status?

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.

response.3DSecure.gatewayCode 3DSecure.enrollmentStatus 3DSecure.authenticationStatus Submit payment operation
CARD_ENROLLED ENROLLED - (Proceed to authentication)
NOT_ENROLLED_NO_ERROR_DETAILS NOT_ENROLLED - Yes
NOT_ENROLLED_ERROR_DETAILS_PROVIDED NOT_ENROLLED - Yes
ENROLLMENT_STATUS_UNDETERMINED_NO_ERROR_DETAILS ENROLLMENT_STATUS_UNDETERMINED - Yes
ENROLLMENT_STATUS_UNDETERMINED_ERROR_DETAILS_PROVIDED ENROLLMENT_STATUS_UNDETERMINED - Yes
AUTHENTICATION_SUCCESSFUL ENROLLED AUTHENTICATION_SUCCESSFUL Yes
AUTHENTICATION_ATTEMPTED ENROLLED AUTHENTICATION_ATTEMPTED Yes
AUTHENTICATION_NOT_AVAILABLE_NO_ERROR_DETAILS ENROLLED AUTHENTICATION_NOT_AVAILABLE Yes
AUTHENTICATION_NOT_AVAILABLE_ERROR_DETAILS_PROVIDED ENROLLED AUTHENTICATION_NOT_AVAILABLE Yes
AUTHENTICATION_FAILED ENROLLED AUTHENTICATION_FAILED No(not allowed)
MPI_PROCESSING_ERROR ENROLLED - Yes
ACS_SESSION_TIMEOUT ENROLLED - Yes
ERROR_PARSING_AUTHENTICATION_RESPONSE ENROLLED - No(failure)
INVALID_SIGNATURE_ON_AUTHENTICATION_RESPONSE ENROLLED - No(failure)
CARD_DOES_NOT_SUPPORT_3DS - - No(failure)
ERROR_PARSING_CHECK_ENROLLMENT_REQUEST - - No(failure)
INVALID_DIRECTORY_SERVER_CREDENTIALS - - Yes (with no 3DS data)
ERROR_PARSING_CHECK_ENROLLMENT_RESPONSE - - Yes (with no 3DS data)
ERROR_COMMUNICATING_WITH_DIRECTORY_SERVER - - Yes (with no 3DS data)
VERes is the message returned by the card scheme to the Mastercard Payment Gateway in response to a request to check 3DS enrollment. PARes is the response message returned to the Mastercard Payment Gateway in response to a request for payer authentication.

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

VERes.enrolled 3DSecure.enrollmentStatus
Y ENROLLED
N NOT_ENROLLED
U ENROLLMENT_STATUS_UNDETERMINED

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

PARes.status 3DSecure.authenticationStatus
Y AUTHENTICATION_SUCCESSFUL
N AUTHENTICATION_FAILED
U AUTHENTICATION_NOT_AVAILABLE
A AUTHENTICATION_ATTEMPTED
How do I view authentication details in the Merchant Administration portal?

If you submitted 3DS details on a transaction, search for the order or transaction in the Merchant Administration portal. 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 the Merchant Administration portal.

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

Payment Client/Virtual Payment Client API
New Codes Old Codes response.3DSecure.gatewayCode
E E NOT_ENROLLED_NO_ERROR_DETAILS
Z NOT_ENROLLED_ERROR_DETAILS_PROVIDED
C C CARD_DOES_NOT_SUPPORT_3DS
B U ENROLLMENT_STATUS_UNDETERMINED_NO_ERROR_DETAILS
V ENROLLMENT_STATUS_UNDETERMINED_ERROR_DETAILS_PROVIDED
F F ERROR_PARSING_CHECK_ENROLLMENT_REQUEST
A A INVALID_DIRECTORY_SERVER_CREDENTIALS
W U ERROR_PARSING_CHECK_ENROLLMENT_RESPONSE
D D ERROR_COMMUNICATING_WITH_DIRECTORY_SERVER
I I MPI_PROCESSING_ERROR
P P ERROR_PARSING_AUTHENTICATION_RESPONSE
S S INVALID_SIGNATURE_ON_AUTHENTICATION_RESPONSE
T T ACS_SESSION_TIMEOUT
X U AUTHENTICATION_NOT_AVAILABLE_NO_ERROR_DETAILS
U AUTHENTICATION_NOT_AVAILABLE_ERROR_DETAILS_PROVIDED
Y Y AUTHENTICATION_SUCCESSFUL
N N AUTHENTICATION_FAILED
M M AUTHENTICATION_ATTEMPTED
R   CARD_ENROLLED
Testing Your Integration

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

Copyright © 2020 Mastercard