DocsGuidesSDKsAPI
Dashboard

Perform a 3D-Secure Authentication

The Evervault API facilitates payment authentication using 3D-Secure. Completing a 3D-Secure authentication involves three simple steps:

  1. Initiate a 3D-Secure Session: Begin by initiating a 3D-Secure session through the Evervault API from your backend. This step sets up the necessary parameters and context for the authentication process.
  2. Render the 3D-Secure Authentication Modal: Using the Evervault js SDK, render the banking/issuer authentication modal on the frontend. This modal allows customers to authenticate with their bank.
  3. Retrieve the Authentication Credentials: Once the customer has authenticated, retrieve the 3DS cryptogram and ECI (Electronic Commerce Indicator) from the Evervault API. These credentials can then be used with any payment gateway during the payment processing stage to confirm a successful 3D-Secure authentication.

Initiate a 3D-Secure Session

The initial step in the authentication process involves creating a 3D-Secure (3DS) session using the Evervault API. This session includes essential details such as payment information, merchant data, and customer specifics, which you must provide when creating the session to assist the card issuer in evaluating the payment’s risk level.

To initiate a 3DS session, call the Create 3DS Session endpoint as shown below:

Once a session is created, Evervault performs several key actions:

  1. Verify that the card issuer supports 3D-Secure.
  2. Identify if any additional data is needed from the frontend application (either the merchant’s website or app) before starting the 3D-Secure Frictionless flow.
  3. Decide the next steps to proceed with the session, such as triggering a 3D-Secure challenge in the frontend or collecting browser/device data.

Evervault will then respond with the created 3DS session, which includes a unique identifier and a status. The status can be one of the following: success, failure, or action-required. This status indicates whether the session is complete or if additional steps are necessary to finalize the authentication process.

  • Success (success): If the session is successful, the ECI (Electronic Commerce Indicator) and 3DS Cryptogram will be included in the response. These can be used to process the payment through your payment gateway. The session is complete and no further action is required.
  • Failure (failure): If the session fails, the response contains a failure reason (failureReason), allowing for troubleshooting.
  • Action Required (action-required): If further action is needed, proceed to the next step of this guide to render the 3DS modal and complete the authentication.

Render the 3D-Secure Authentication Modal

In order to proceed with the 3D-Secure session and render the 3DS modal, you first need to include our JavaScript SDK.

Next, initialize the SDK by passing your Team ID and App ID to the Evervault constructor. Then, mount a ThreeDSecure UI Component from the Evervault JS SDK to handle the 3D-Secure process.

The ThreeDSecure UI component can be initiated using the evervault.ui.threeDSecure method by passing the session ID obtained in the previous step. Once you have intialized the ThreeDSecure Component, you can call the .mount() method to open the 3DS modal in the customer's browser, allowing the 3D-Secure authentication to occur. The success event will be fired once the 3D Secure authentication process has been completed successfully. The failure event will be fired if the authentication process fails (e.g. the customer failed to authenticate).

You can learn more about integrating the 3DS-Secure modal into your web app by visiting our dedicated JavaScript and React documentation.

During this step, Evervault performs several operations in the background:

  1. The Evervault SDK collects data from the browser, such as the user agent, IP address, and browser language. It then executes the 3DS method, which allows the card issuer to gather data about the current browser session. This involves redirecting the cardholder to the banking website using a hidden iframe, enabling seamless data collection without disrupting the user experience.

  2. Evervault sends the 3DS Authentication Request to the card issuer as part of the 3DS frictionless flow. This request allows the card issuer to perform a comprehensive risk assessment based on the collected data and determine the appropriate level of authentication required.

  3. Finally, Evervault handles the 3DS redirection to the card issuer’s or bank’s website, facilitating the authentication process if needed.

Retrieve the Authentication Credentials

Upon completing the 3D Secure session using the Evervault JavaScript SDK, you can retrieve the Electronic Commerce Indicator (ECI) and 3DS cryptogram from the Evervault API via the Retrieve 3DS Session endpoint.

Once obtained, these values (ECI and cryptogram) should be forwarded to your payment gateway to successfully process the charge.