3D Secure

Overview

A transaction that qualifies for 3D Secure 2 can go through either a frictionless flow or a challenge flow, depending on the issuer's requirements.

A. 3D Secure 2 Frictionless Authentication Flow

In a frictionless flow, the acquirer, issuer, and card scheme exchange all necessary information in the backend through passive authentication using the user's device fingerprint. The transaction is completed without further user interaction.

B. 3D Secure 2 Challenge Authentication Flow

In a challenge flow, the issuer requires additional user interaction, either through biometrics, two-factor authentication, a one-time authentication code received on user's phone or a password.

C. EVO Cloud Implementation

In EVO Cloud, each merchant is configured with one of the following options on the store level:

Non-Authentication:

Your store is not applied to authentication; all payments will NOT go through the authentication flow.

With this option, you CANNOT enable the tokenization feature.

Require-Authentication:

Your store is required to perform authentication for every card payment.

You must submit the authentication-related fields in your initial payment request.

With this option and the required tokenization parameters set up, you can enable the tokenization feature.

After the authentication has been completed, the authentication result parameter threeDS.mpiData or securePlus.securePlusData will be returned in the response message.

Optional-Authentication:

It is up to you to decide whether to perform the authentication before payment using the allowAuthentication field when making the payment request.

If you specify allowAuthentication as true, you must submit the authentication-related fields in your initial payment request.

With this option and the required tokenization parameters set up, you can enable the tokenization feature.

After the authentication has been completed, the authentication result parameter threeDS.mpiData or securePlus.securePlusData will be returned in the response message.

EVO Cloud 3D Secure Support Options

EVO Cloud provides the following 2 options to support both 3D Secure versions:

Redirect for 3D Secure 2:

Implement the fastest way to support 3D Secure by redirecting the user to another site to verify the payment.

This mode is named threeDSPage, and it is the default setting in EVO Cloud when you integrate 3D Secure processing, unless you specify authentication.type as threeDSIntegrator to choose the other option.

Redirect for 3D Secure 2

EVO Cloud implements 3D Secure 2 using a redirection. EVO Cloud will check which version the issuer supports and provide a redirect URL where the user can complete 3D Secure 2 authentication.

This is the easiest way to support 3D Secure, as most of the backend processing steps are handled by the redirect URL provided by EVO Cloud.

The diagram above describes both server-side integration and the client-side implementation that you have to build.

Step 1: Collect Additional Parameters

In addition to the basic parameters collected in Payment / Tokenization, you need to gather additional information from your user to perform 3D Secure authentication. You can obtain the list of additional parameters from the authenticationInfo array returned in the HTTP GET response for /g2/v1/payment/mer/{sid}/paymentMethod. See Step 2 in Chapter Payment for more details.

Step 2: Make a Payment or Tokenization

With the additional parameters collected, make an HTTP POST request from your server to the EVO Cloud endpoint:

/g2/v1/payment/mer/{sid}/payment

for payment. Or to

/g2/v1/payment/mer/{sid}/paymentMethod

for tokenization.

Here are the additional parameters required in the request for 3D Secure authentication with threeDSPage mode:

Body Parameter	Required	Description
`authentication`	O	The information used for user authentication before payment or tokenization.
`transInitiator`	M	The information used for user authentication before payment or tokenization.
`transInitiator.browserInfo`	O	The user browser information for 3DS authentication, which will be sent to the authentication service provider.
`userInfo`	O	The information used for user authentication before payment or tokenization.
`returnURL`	M	The URL to redirect your customer back to after they complete the authentication.
`authenticationOnly`	O	In POST `/g2/v1/payment/mer/{sid}/payment` request, indicates whether it is an authentication-only payment request. See Chapter Authentication Only for more details.
`allowAuthentication`	O	Applied when your store is configured as Optional-Authentication. In POST `/g2/v1/payment/mer/{sid}/payment` or POST `/g2/v1/payment/mer/{sid}/paymentMethod` request to indicate whether the payment needs to conduct authentication. Note that this field does not apply when `authenticationOnly` is true.

More details about the authentication object:

authentication.type: The authentication mode applied for this payment, optional. You can specify it as threeDSPage, which is also the default value, to inform EVO Cloud that you want to use the redirection solution for 3D Secure 2.

authentication.threeDS.merchantRiskIndicator: The object containing the additional risk fields for 3D Secure 2, optional. See EVO Cloud API Specification for more details.

More details about the transInitiator object:

transInitiator.userCreateIP: The IP address of the device that initiates the payment, optional.

transInitiator.browserInfo.acceptHeader: The accept header value of the user's browser, required.

transInitiator.browserInfo.colorDepth: The color depth of the user's browser in bits per pixel, required. Use the browser's screen.colorDepth property to obtain the value. Accepted values: 1, 4, 8, 15, 16, 24, 32, or 48 bits.

transInitiator.browserInfo.javaEnabled: A Boolean value indicating whether the user's browser is able to execute Java, required.

transInitiator.browserInfo.language: The browser language defined in IETF BCP47, required. Use the browser's navigator.language property to obtain the value. For example, NL, FR, US.

transInitiator.browserInfo.screenHeight: The total height of the user's screen in pixels, required. Use the browser's screen.height property to obtain the value.

transInitiator.browserInfo.screenWidth: The total width of the user's screen in pixels, required. Use the browser's screen.width property to obtain the value.

transInitiator.browserInfo.timeZoneOffset: The time difference in minutes between the UTC time and the local time of the user's browser, required. Use the browser's getTimezoneOffset() method to obtain the value.

transInitiator.browserInfo.userAgent: The user agent value of the user's browser, required.

More details about the userInfo object:

userInfo.billingAddress: The object containing the user's billing address, optional. See EVO Cloud API Specification for more details.

userInfo.deliveryAddress: The object containing the address to deliver the goods, optional. See EVO Cloud API Specification for more details.

userInfo.accountInfo: The object containing the user account information for 3D Secure 2, optional. See EVO Cloud API Specification for more details.

userInfo.email: The user's email address, optional.

Here is an example of making a 10 USD payment with credit card requiring 3D Secure authentication:

If you don't receive an action object in the response, use the result.code and payment.status / paymentMethod.token.status to present the payment / tokenization result to your user.

Otherwise, additional steps are required to complete the payment / tokenization, you need to send the action object to your web frontend or client APP, then proceed to the next step.

Here is an example of the response of the payment that requires a redirection:

Step 3: Process threeDSRedirect

For the redirection solution for 3D Secure 2 (authentication.type is threeDSPage), usually the action.type you received in the response is threeDSRedirect, meaning that you need to redirect the user to an EVO Cloud hosted page to complete the 3DS 2 authentication with action.threeDSData in the same response.

A. Redirect User to EVO Cloud Hosted Page

Redirect the user to action.threeDSData.url using the HTTP method specified in action.threeDSData.method.

Here is an example of performing the threeDSRedirect action on your frontend when action.threeDSData.method is GET:

tip

Please note that the user is then redirected to an EVO Cloud hosted page, and then EVO Cloud will process the following 3D Secure authentication procedures with the user and issuer ACS.

B. Redirect Back After User Completes the Authentication

The user will be redirected back by EVO Cloud to your returnURL with an HTTP GET request within 10 minutes. You can use the merchantTransID parameter in the response to match your initial request.

If the status parameter in the response is finished, the 3D Secure authentication is successful. You will need to obtain the transaction details by requesting the GET interface or receiving a notification from EVO Cloud.

If you do not receive any response within 10 minutes, or if the status parameter is not finished, the 3D Secure authentication has failed. In this case, you should obtain the transaction details by requesting the GET interface or receiving a notification from EVO Cloud.

Step 4: Present the result

After the user completes the payment or tokenization, and no further actions are required on the frontend or client app, you can receive a notification or initiate a GET request to obtain details. Use the result.code and payment.status / paymentMethod.status to inform your user of the payment or tokenization status.

Result Code	Description
S0000	Success

For other possible result.code values and recommended messages that you can present to your user, see the Appendix in the EVO Cloud API Specification.

Status	Description
Authorised	Used for card transactions; means the transaction authorization is successfully completed and pending for capture (the merchant can submit a cancel).
Captured	For card transactions, means transaction authorization and capture are successfully completed; for e-wallet transactions, means the transaction is successfully completed.
Failed	Payment failed

Status	Description
Success	Means the token is created
Failed	Means token creation failed

For other possible payment.status / paymentMethod.status values and descriptions, see payment.status / paymentMethod.status in the EVO Cloud API Specification.

Error handling

For HTTP POST request to EVO Cloud: It is suggested to wait at least 45 seconds after the request is sent to EVO Cloud. If you don’t get the response within the time frame, you need to retrieve the result from EVO Cloud. See Step 6 in chapter Payment / Tokenization to initiate the request.

For HTTP PUT request to EVO Cloud: The HTTP PUT request is idempotent, meaning that if you don’t get the response from EVO Cloud within a certain time frame, for example 45 seconds, you can resend the request with exactly the same request message. If you still fail to get the response after several times of the request, you can initiate another payment / tokenization request instead.

Overview#

Redirect for 3D Secure 2#

Step 1: Collect Additional Parameters#

Step 2: Make a Payment or Tokenization#

Step 3: Process threeDSRedirect#

Step 4: Present the result#

Error handling#

Overview

Redirect for 3D Secure 2

Step 1: Collect Additional Parameters

Step 2: Make a Payment or Tokenization

Step 3: Process threeDSRedirect

Step 4: Present the result

Error handling