3-D Secure Authentication
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 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 Gateway.
3DS payer experience
This section describes a sample checkout flow for your shop site where the payer is authenticated using 3DS.
The checkout flow for a successful authentication is as follows:
- 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.
- Check 3DS Enrollment: You ask the Mastercard Gateway to check with the card scheme if the card is enrolled for 3DS
- 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.
- Process ACS Result: You ask the Mastercard Gateway to process the authentication result. Mastercard Gateway provides you with details of the authentication response received from the issuer.
- Use the 3DS Result in a Payment Operation: You submit the payment for processing
- You display the order confirmation page to the payer.
Integrating to use 3DS authentication
This section describes how to integrate to the Mastercard Gateway to use 3DS.
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 processorder.amount: the total amount of the orderorder.currency: the currency of the ordersourceOfFunds.provided.cardorsession.idorsourceOfFunds.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 Gateway provides the results of the enrollment check in the response:
3DSecure.xid: A unique transaction identifier generated by the Mastercard Gateway for the 3DS authentication.3DSecure.summaryStatus: a summarized response indicating the overall card enrollment statusresponse.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 |
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 Gateway provides the results of the authentication in the response:
3DSecure.summaryStatus: a summarized response indicating the overall authentication statusresponse.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 |
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 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 Gateway will pass the required information to the acquirer.
Other options
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.
The HTML required for the form used to redirect the payer for authentication may be generated using one of two page generation methods:
Simple: the Mastercard Gateway generates the HTML form. The complete form is returned in the Check 3DS Enrollment response. This is the default option.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.expectedHtmlEncoding3DSecure.authenticationRedirect.simple.redirectDisplayBackgroundColor3DSecure.authenticationRedirect.simple.redirectDisplayContinueButtonText3DSecure.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.
3DSecure.summaryStatus = AUTHENTICATION_ATTEMPTED, you provide 3DSecure.authenticationToken.Preauthenticated 3DS on Authorize API Reference [REST] [NVP]
If you wish to retrieve the authentication results at any stage, use the Retrieve 3DS Result operation.
FAQs
The Mastercard 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) |
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 |
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:
| Payment Client/Virtual Payment Client | DirectAPI | |
|---|---|---|
| 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 |
|
You can test your integration for performing 3DS Authentication via the Mastercard 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:
- Use a 3D-Secure Enrolled test card (see cards listed in the specific Acquirer sections) when submitting the
CHECK_3DS_ENROLLMENTrequest for your Test Merchant Profile. - Check that you receive a response with
response.3DSecure.gatewayCode=CARD_ENROLLED. - Use the form provided in
3DSecure.authenticationRedirect.simple.htmlBodyContentto 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.
- Submit a
PROCESS_ACS_RESULTrequest with the PARes in3DSecure.paRes. - Use the ID for this 3D-Secure Authentication via the Mastercard Gateway provided in
3DSecureIdin a subsequent transaction request (e.g.PAYorAUTHORIZE).