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

Some request/response fields for 3DS operations have been updated in API version 47. For integration support on previous versions (<=46 ), click here.

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.

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.

Step 1: 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.

    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.

response.gatewayRecommendation Next step
PROCEED You can proceed to authenticate the payer.
DO_NOT_PROCEED Do not proceed with 3DS authentication for this card. You can offer the payer the option to try another payment method.

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.

3DSecure.veResEnrolled 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 by providing 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 by providing the 3DSecureId on the request.

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

Step 2: Authenticate Payer

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.

This is the default.  You may also choose to customize the form.
Step 3: 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 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.

response.gatewayRecommendation Next step
PROCEED You can proceed with the payment operation by providing the 3DSecureId on the request.
DO_NOT_PROCEED Do not proceed to submit a payment operation. You can offer the payer the option to try another payment method.

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.

3DSecure.paResStatus Next step
Authentication successful Authentication of the payer was successful. Proceed with the payment operation by providing 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 by providing the 3DSecureId on the request.
Authentication not available There was an error. Proceed with the payment operation by providing the 3DSecureId on the request.

Process ACS Result API Reference [REST] [NVP]

Step 4: 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 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.

Some authentication results are authentication failures for which a payment should not be processed. In these cases, the gateway will return result = ERROR in the response for the payment operation. You can offer the payer the option to try 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 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]

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 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.
Mastercard/Visa require that if you are using Mastercard SecureCode/Verified by Visa, and if authentication was attempted, you must provide authentication.3ds.authenticationToken.

Pre-authenticated 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 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.

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 Authentications search option in the Merchant Administration portal.

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.

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

Copyright © 2020 Mastercard