3D Secure

3D Secure is an online payment security protocol designed to reduce fraud and provide an additional layer of authentication for online transactions. When a customer makes an online purchase, 3D Secure requires them to complete an additional verification step with the card issuer, typically through a password, biometric authentication, or a one-time passcode sent over SMS.

How 3D Secure works

3D Secure consists of several steps involving both merchants and card issuers to allow customers to be authenticated during online purchases:

1. 1.

   Payment Initiation

   When a customer initiates an online purchase and enters their card details on the merchant's website, the merchant recognizes that the card is enrolled in 3D Secure and triggers the authentication process.

2. 2.

   Issuer Challenge

   The customer is redirected to a web page hosted by their card issuer where the customer is asked to authenticate themselves. This can be done through various methods, such as entering a static password, a one-time password (OTP) sent over SMS, or using biometric authentication (e.g., fingerprint or facial recognition).

3. 3.

   Process Payment

   If the authentication is successful, the merchant processes the authenticated transaction and the customer is redirected back to the merchant’s website with a confirmation of their purchase. If the authentication fails or is not completed, the transaction is typically declined, and the customer is informed of the failure.

The Benefits of 3D Secure

Implementing 3D Secure for online payments provides several benefits for both merchants and customers, enhancing overall transaction security and achieving regulatory compliance:

• Reduced Fraud

  By requiring an additional authentication step, 3D Secure significantly decreases the risk of unauthorized transactions. This added security measure helps to ensure that the person using the card online is the legitimate cardholder.

• Liability Shift

  One of the key advantages for merchants using 3D Secure is the liability shift. If a transaction is authenticated using 3D Secure and later turns out to be fraudulent, the liability for the chargeback shifts from the merchant to the card issuer. This can result in substantial cost savings and reduced chargeback rates for merchants.

• Regulatory Compliance

  With the increasing emphasis on online transaction security and regulations such as PSD2/SCA in Europe, implementing 3D Secure helps merchants comply with these regulations and avoid potential fines and penalties.

Getting started with 3D Secure

Evervault provides a set of easy-to-use APIs designed to let you perform 3D Secure Authentications in minutes without having to integrate directly with the card networks. Completing a 3D Secure authentication involves three steps:

• Creating a 3DS Session
• Authenticating the Session on the client
• Forwarding the authentication credentials to your payment gateway

Before getting started, you will need to create Sandbox app. Sandbox apps allow you to test 3D Secure without affecting live data. Once you're ready to transition to Live Mode for processing real authentications, please contact our support team to enable 3D Secure on your production app.

Initiate a 3D Secure Session

The first step in the authentication process is to create a 3D Secure (3DS) session using the create session API endpoint by providing the card, merchant, and payment details. This should be done from your backend service and you should pass the session ID to your client code.

1const response = await fetch("https://api.evervault.com/payments/sesssions", {
2  method: "POST",
3  headers: {
4    "Content-Type": "application/json",
5    "Authorization": "Basic <credentials>"
6  },
7  body: {
8    card: {
9      number: "4242424242424242",
10      expiry: {
11        month: "05",
12        year: "25"
13      }
14    },
15    merchant: {
16      name: "Ollivanders Wand Shop",
17      website: "https://www.ollivanders.co.uk",
18      categoryCode: "5945",
19      country: "ie"
20    },
21    payment: {
22      amount: 1000,
23      currency: "eur"
24    }
25  }
26})
27
28const session = await response.json();

Display the 3D Secure authentication challenge

Once you have a 3D Secure session, the next step is to present the 3D Secure challenge to the customer. This can be done either by using our client-side SDK or as a full page redirect. We highly recommend using our SDK where possible, to ensure compatibility with future changes.

Using the Client-Side SDK

Once you have created a 3DS session, you should use our client-side SDK to perform 3D Secure authentication for that session.

1<script src="https://js.evervault.com/v2"></script>

1const evervault = new Evervault("<TEAM_ID>", "<APP_ID>");

1import { loadEvervault } from "@evervault/js";
2
3const evervault = loadEvervault("<TEAM_ID>", "<APP_ID>");

1const evervault = new Evervault("{{TEAM_ID}}", "{{APP_ID}}");
2const threeDSecure = evervault.ui.threeDSecure("tds_visa_5a9a7b0a574c");
3
4threeDSecure.on("success", () => {
5  // 3DS is complete and payment can be finalized
6});
7
8threeDSecure.on("failure", () => {
9  // 3DS failed. Try again.
10});
11
12threeDSecure.mount();

Using a page redirect

The 3D Secure challenge can also be loaded directly—either through a full page redirect or served within an <iframe> or mobile web view. In this scenario, fingerprinting and challenge windows are presented directly in the user's browser. Once the 3D-Secure Authentication has been finalized (with either a success, a failure, or an error) the page is redirected back to a callback URL of your choice.

1https://3ds.evervault.com/?team=<TEAM>&app=<APP>&session=session&redirect=redirect

Once the 3D-Secure Session has been finalized, the page will redirect back to the URL provided in the redirect parameter with status and session appended to the URL parameters. More details about the 3D-Secure Session can be retrieved from our API.

Retrieve the authentication credentials

After completing the 3D Secure session using the Client-Side 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.

1const response = await fetch(
2  "https://api.evervault.com/payments/sessions/tds_visa_5a9a7b0a574c",
3  {
4    headers: {
5      Authorization: "Basic <credentials>",
6    },
7  }
8);
9
10const session = await response.json();
11
12console.log(session.cryptogram);
13// MTIzNDU2Nzg5MDA5ODc2NTQzMjE=
14
15console.log(session.eci);
16// { "value": "05", "descriptor": "fully-authenticated", "liabilityShift": true }

1const tds = evervault.ui.threeDSecure("tds_visa_5a9a7b0a574c", {
2  failOnChallenge: true,
3});

Configuring Acquirer Details

Acquirer configuration is required for 3D-Secure authentications in production. While acquirer details are not needed when testing in Sandbox mode, you must configure them before processing live transactions.

When you process 3D-Secure authentications in production, the card networks require information about your payment acquirer (the bank or payment processor that handles your card transactions). This acquirer information is necessary for the authentication process to work correctly.

Default Acquirer details

Evervault recommends configuring your acquirer details using the Acquirers API. This allows you to store your acquirer configurations securely, and reuse them across all your 3D-Secure sessions without needing to pass acquirer details with every API request.

• Simplified integration: You don't need to include acquirer details every time you create a 3DS session
• Better security: Acquirer details are stored securely and aren't exposed in your application code
• Easier management: Update acquirer details in one place when your payment processor changes
• Multi-network support: Configure different acquirer details for each card network (Visa, Mastercard, etc.)

Setting up default acquirer details

You can configure a default acquirer for each card network (Visa, Mastercard, American Express). When creating a 3DS session, Evervault uses the appropriate acquirer configuration based on the card network.

You can use the Acquirers API to configure your acquirer details for production. Configurations are specific to each app, so you need to configure these for your staging and production apps separately.

Provide acquirer details per request

Alternatively, you can provide acquirer details when creating each 3DS session by including the acquirer object in your API request. This approach is useful if you work with multiple acquirers or need to specify different acquirer details for different transactions. However, supplying acquirer details per request adds complexity to your integration. You'll likely need to perform a BIN lookup to identify the card network, so that you can then decide which acquirer BIN or MID values to provide for each transaction.

How Evervault resolves acquirer details

When you create a 3DS session, Evervault follows this process to determine which acquirer configuration to use:

1. Explicit acquirer details: If your request includes an acquirer object, those details are used.
2. Configured acquirer reference: If your request includes an ID of an acquirer configuration in the acquirer field, that configuration is used.
3. Default acquirer: If no acquirer details are provided in the request, Evervault uses the default acquirer configuration for the card's network, if available.
4. No configuration found: If no acquirer details can be resolved, session creation fails.

Testing your implementation

Provided you are using a Sandbox app, you can use specific Test Cards to simulate various real-life scenarios. These cards can be used in conjunction with any valid expiry date or CVC.