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. The MasterCard Payment Gateway supports both 3DS versions — 3DS and EMV 3DS.

3DS, also known as 3DS1 in the gateway, is the original version that allows payers to authenticate at their issuer's Access Control Server (ACS) by entering a password previously registered with their card issuer. Supported authentication schemes include Mastercard SecureCode™, Verified by Visa™, American Express SafeKey™, J/Secure™, and Diners Club ProtectBuy™.

EMV 3DS, also known as 3DS2 in the gateway, is the new version designed to enhance security in online purchases while providing frictionless checkouts to payers who are considered low risk by the Access Control Server (ACS). The ACS may determine the risk using information provided by the merchant, browser fingerprinting, and/or previous interactions with the payer. The ACS subjects the payer to a challenge (for example, entering a PIN) only where additional verification is required to authenticate the payer thereby providing increased conversion rates. Supported authentication schemes include Mastercard SecureCode™, Verified by Visa™, American Express SafeKey™, Diners Club/Discover ProtectBuy, and JCB J/Secure.

While your payment service provider can configure both 3DS1 and 3DS2 on your merchant profile with the gateway, you can restrict the versions you want to accept by specifying your choice in the authentication request. If both are accepted then the gateway uses 3DS2 (if supported by the issuer and the card) and falls back to 3DS1 only where 3DS2 is not available. If both are not available, the authentication will not proceed. However, you can still proceed with the payment if the gateway recommends you to do so.

Terminology

Here are some key terms that will be referenced throughout the 3DS integration documentation.

Term	Description
Access Control Server (ACS)	A component that operates in the issuer domain, which verifies whether authentication is available for a card number and device type, and authenticates specific transactions.
ACS Method Call	Applies to 3DS2 authentication. It's a call that allows the ACS to gather additional data to determine the risk score for the payer. When 3DS2 is available and when the ACS call details are returned in the response after initiating the authentication, these details are passed to the payer's browser, which are submitted as a form post in a hidden iframe, so that the ACS can collect additional data.
Frictionless Flow	An authentication flow where the payer is not required to respond to a challenge because the ACS deems the payer as low risk.
Challenge Flow	An authentication flow where the payer is redirected to the ACS and is required to respond to a challenge to identify themselves, because the ACS does not have sufficient payer information to deem the payer as low risk.
Payment Session	A payment session, or simply session, is a temporary container for any request fields and values of operations that reference a session. You can use it in an operation to reference the request fields and values than providing them directly in the operation request. When the gateway receives an operation that references a session, it forms the final request by combining the request fields in the session and those supplied directly in the request. For more information, see payment session.
Session Authentication	Authentication using a payment session. This authentication allows payers to provide their payment details directly to the gateway via a client-side interaction with the gateway, either through a payer's browser or an app on the payer's mobile device. It uses basic HTTP authentication mechanism (similar to password authentication) where you must provide 'merchant.<your gateway merchant ID>' in the userid portion and the session Id in the password portion. To use this authentication type, you must first create a session by submitting a session request (see Create session [REST][NVP]) from your server to the gateway server.
Merchant Authentication	A mechanism that allows the merchant to authenticate API requests to the gateway, for example, password/certificate/session authentication.
Authentication API	A server-side API consisting of two operations, Initiate Authentication and Authenticate Payer, that must be submitted from your server to the gateway server. It can also be used as a client-side API using session-based authentication.
3DS JavaScript API	A client-side JavaScript API that allows you to initiate 3DS authentication from the payer's browser using session-based authentication.
Authentication Channel	Indicates where 3DS authentication is taking place, in the payer's browser, in an app on the payer's mobile device, or in your system with no payer present to interact. These have implications in terms of which authentication types and flows are available, for example, 3DS1 can only be supported in browser with a payer available for interaction with the ACS.
Authentication Purpose	If you are establishing a payment agreement and processing a payment along with it, provide ‘PAYMENT TRANSACTION’ as the Authentication purpose. Agreement details must be provided. If you are establishing a payment agreement and not processing a payment along with it, provide ‘ADD_CARD’ as the Authentication purpose. Agreement details must be provided.

Prerequisites

To use gateway's 3DS authentication service:

You must be registered with your acquirer to use 3DS1 and/or 3DS2
Your merchant profile on the gateway must be enabled for at least one 3DS scheme for a supported 3DS version.
You must be integrated to API version 57 or later.

3DS Authentication Flows

The authentication flow for a payment differs depending on whether the card selected by the payer supports 3DS1 or 3DS2 or both.

3DS1

The diagram below illustrates the authentication flow for a payment where the gateway falls back to 3DS1 authentication because 3DS2 is not available for the card. The gateway will attempt 3DS1 in other cases too, for example, where you are only enabled for 3DS1, or have restricted the authentication version to only 3DS1 in the authentication request.

3-D Secure Authentication Flow for 3DS1

The authentication 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 3DS1 but not 3DS2.
Initiate Authentication: You ask the gateway to check with the card scheme if the card is enrolled for 3DS.
If 3DS1 authentication of the payer is available, the gateway returns the card enrollment details in the response.
If the card supports both 3DS1 and 3DS2, then the gateway attempts 3DS2 first. See 3DS2 flow.
Authenticate Payer: You ask the gateway to perform the initiated authentication.
The gateway provides you with details of the authentication for a challenge flow (where the payer is required to respond to a challenge presented by the issuer).
You redirect the payer’s web browser to the ACS, which presents its authentication UI. The issuer returns the authentication result to the gateway. The gateway redirects the payer directly to your website.
Use the 3DS Authentication Transaction ID in a Payment Operation: You submit the payment for processing.
You display the order confirmation page to the payer.

3DS2

The diagram below illustrates the authentication flow for a payment where the payer is authenticated using 3DS2.

3-D Secure Authentication Flow for 3DS2

The authentication 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 3DS1 and 3DS2.
Initiate Authentication: You ask the gateway to check with the card scheme if the card is enrolled for 3DS.
If 3DS authentication of the payer is available, the gateway returns the authentication details in the response.

The Initiate authentication response contains a "redirect html snippet" that can be included in the customer's browser through a hidden iframe. This will help in minimising the wait time for customers when they receive a "SERVER_BUSY" error; otherwise, they will have to wait for 10 seconds.

The method complete is not provided automatically and you must perform the authenticate payer API to confirm if the method is complete.

The gateway returns details of the supported ACS call. You must submit the ACS call details as a form post in a hidden iframe, so that the ACS can collect additional data.
Authenticate Payer: You ask the gateway to perform the initiated authentication.
The gateway provides you with details of the authentication either for a frictionless flow or a challenge flow (where the payer is required to respond to a challenge presented by the issuer).
1. Frictionless Flow: The gateway redirects the payer directly to your website.
2. (Optional) Challenge Flow: If the issuer requires the payer to respond to a challenge, you redirect the payer’s web browser to the ACS, which presents its authentication UI. The issuer returns the authentication result to the gateway. The gateway redirects the payer directly to your website.
Use the 3DS Authentication Transaction ID in a Payment Operation: You submit the payment for processing.
You display the order confirmation page to the payer.

3DS Authentication Modes

The gateway supports the following 3DS authentication modes:

Authentication Only: You perform 3DS authentication using the gateway. You can choose to submit the payment (using the authentication details) at a later stage via this gateway or another gateway.
Authentication and Payment Transaction: You perform 3DS authentication using this gateway and proceed to submit the payment (using the authentication details) via this gateway.
Pre-authenticated Payment Transaction: You perform 3DS authentication using an external provider and supply the authentication details when submitting a payment via this gateway.

Adding 3DS to Your Integration

The gateway supports the following integration options for 3DS.

Integration Option	When to Use	Supported Transaction Modes
Hosted Checkout	This is the easiest integration option. With Hosted Checkout integrations version 57 and later, you must select 3-D Secure Authentication from the Payer Authentication dropdown, in the Admin > Integration Settings page of the Merchant Administrator user interface. To initiate 3DS authentication and other 3DS operations directly from the payer's browser, you must first establish the authentication channel where your merchant server must communicate with the gateway server for creating a session on the gateway. The gateway generated session Id is then included in all browser-initiated authentication requests as the password parameter (see session-based authentication)	Authentication and Payment Transaction
3DS JavaScript API	This is a client-side JavaScript integration if you want to initiate 3DS authentication from your website's payment page. Use this option if you want to allow the payer to submit their payment details directly to the gateway from the browser. To initiate 3DS authentication and other 3DS operations directly from the payer's browser, you must first establish the authentication channel where your merchant server must communicate with the gateway server for creating a session on the gateway. The gateway generated session Id is then included in all browser-initiated authentication requests as the password parameter (see session-based authentication).	Authentication Only Authentication and Payment Transaction
Authentication API	This is a server-side integration option that gives you total control over your integration but requires the highest integration effort. Use this option if you are required to customize API interactions between the payer's browser and the gateway. You must perform operations needed for managing the 3DS integration flows directly from your merchant server to the gateway server. It can be used as a client-side API using session-based authentication.	Authentication Only Authentication and Payment Transaction.