3D Secure

Pricing
Sandbox support

Reduce fraud and increase security for online transactions

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.

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.

How 3D Secure works

3D Secure consists of several steps involving merchants, card networks, and card issuers to allow customers to be authenticated during online purchases. At a high level, a standard challenge flow looks like this.

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 isn't completed, the transaction is typically declined, and the customer is informed of the failure.

3DS supports frictionless authentications as well, which require no interaction from the customer. A frictionless flow is initiated when the issuer determines that a transaction is low-risk, eliminating the need for additional verification steps. Frictionless authentications aren't always possible, but they provide a much smoother customer experience because there's no challenge displayed to the customer, meaning there's no action for them to take.

3DS with Evervault

Although the 3DS protocol is known for being difficult to work with, we built our solution from scratch (and we run our own 3DS server). We did this to make our API straightforward to use. We don't wrap other solutions, and our API isn't just a one-to-one mapping of the 3DS protocol. We manage a lot of the complexity for you, and surface just the parts you need to configure and control 3DS the way you want to. Completing a 3DS authentication with Evervault takes three steps:

1. Create the session
2. Run the session on your frontend
3. Retrieve and forward authentication credentials as needed

That last step is an important differentiator. Because our solution is standalone, you can use 3DS authentications with any downstream partner. This is especially important for integrating with multiple payment service providers (PSPs). You could integrate with each PSP and use their 3DS solutions, but there are some issues with that. You're limited on the configuration side to whatever the PSPs allow, and it makes for an inconsistent customer experience because each 3DS implementation is different. Evervault lets you configure your own 3DS flows, and then share the results with any PSP, and customers always see the same interface.

Get started with 3D Secure

To start, you need to create a Sandbox app. Sandbox apps allow you to test 3D Secure without affecting live data. When you're ready to go live, contact our support team to enable 3D Secure on your production app.

1. Create a 3DS session

Use the create session endpoint by providing the card (in encrypted form using our card collection, as a network token, or in plaintext), merchant, and payment details. Do this from your backend and then pass the session ID to your client code.

1const response = await fetch("https://api.evervault.com/payments/3ds-sessions", {
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      type: "one-off",
23      amount: 1000,
24      currency: "eur"
25    }
26  }
27})
28
29const session = await response.json();

3DS Requestor Initiated (3RI) transactions

Merchant-initiated transactions (MIT) are commonly used to charge customers for subscriptions, installment payments, etc. 3RIs are a form of MIT that include a 3DS authentication without the cardholder being present (flows are frictionless and either succeed or fail, there's no challenge involved). These 3RIs are often used instead of standard MITs because they can improve acceptance rates and may still result in liability shift (moving chargeback liability from you to the issuer).

To use 3RIs, you still complete initial 3DS sessions with customers. You keep track of the session ID, and then you use it later to create a 3RI which carries over the authentication. If the initial session's status isn't success, creating the 3RI fails with a 400 error. To create a 3RI transaction, set the:

• Initiator type to merchant
• initialSession to the ID returned from the original session or a threeDSServerTransactionID
• Payment type to recurring or installment

Visa Data Only authentication

Visa's Digital Commerce Authentication Program (DCAP) lowers interchange fees on transactions authenticated through Visa's Data Only flow. Rather than challenging the cardholder, Data Only sends enriched transaction data to Visa for risk assessment. The customer sees no challenge, and you pay a lower interchange rate.

Like 3RIs, a Data Only session authenticates as soon as it's created, so you don't mount the SDK on your frontend. Collect the extra data points along with the usual 3DS data, and Evervault authenticates the session when you create it.

To create a Data Only session for a Visa card, set the challenge preference to no-challenge-requested and the reason to data-sharing, and supply all of the following:

• The customer's full billing address, including state
• The customer's phone and email
• A deviceId you generate for the customer's device
• The customer's clientIp

Evervault reports the outcome on the dcap object, which is present on every Visa session created with a data-sharing reason.

Retrieve and forward the authentication credentials after creating the session, as you would for any other session. Evervault also recommends combining Data Only with network tokens, which reduce interchange further.

2. Run the session on your frontend

After creating the session, use our client-side SDKs to complete the authentication flow on your frontend. If for some reason you can't use our SDKs, you can try using a redirect but Evervault doesn't generally recommend this (redirects add friction to the customer experience).

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();

3. Retrieve and forward authentication credentials

After completing the authentication, you can retrieve information about the session as needed. To process the transaction and ensure liability is shifted, pass the raw Electronic Commerce Indicator (ECI) and 3DS cryptogram to your payment gateway or PSP.

1const response = await fetch(
2  "https://api.evervault.com/payments/3ds-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 }

In some cases, downstream partners might also require one or more of these IDs:

• threeDSServer.transactionIdentifier
• directoryServer.transactionIdentifier
• accessControlServer.transactionIdentifier

These values are specific to the 3DS protocol, and not Evervault. They're sometimes requested in addition to the ECI and cryptogram, but not every provider requires them.

Configuring acquirer details

Acquirer details aren't required in Sandbox mode but you do need them to use 3DS in production. Evervault automatically passes this information in when 3DS sessions are created, although you can pass values in manually yourself.

You can configure acquirers in the dashboard or with the API, and you can set up default acquirers for each card network (Visa, Mastercard, etc.). When creating a 3DS session, Evervault uses the appropriate acquirer configuration based on the card network. Configurations are specific to each app, so you need to configure these for your staging and production apps separately.

Acquirer info request template

If you need to obtain acquirer information from one of your partners (e.g., PSPs), you can use the template message below to request it. It covers everything you need to configure acquirers within Evervault.

1Hi,
2
3We're currently integrating Evervault as our 3D-Secure (3DS) Server provider and need to collect some information related to our merchant account to unblock our integration.
4Could you please provide the following details for each network we're set up with? There should be different acquirer BIN values for each of Visa, Mastercard, Discover, and American Express.
5
6- Merchant ID (MID): Our merchant account number/merchant ID.
7- Acquirer BIN: The numeric identifier you've received from each card network to represent the underlying acquiring bank. These should be 6-10 digits in length.
8- Merchant Name: The official name you have on file for us.
9- Merchant Category Code (MCC): Our four-digit business classification assigned by the card networks.
10
11Thank you!

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. If your request includes an acquirer object, those details are used.
2. If your request includes an ID of an acquirer configuration in the acquirer field, that configuration is used.
3. If no acquirer details are provided in the request, Evervault uses the default acquirer configuration for the card's network, if available.
4. 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.

Troubleshooting 3DS failures

There are a lot of places in the 3DS flow that can fail. In most cases, Evervault's failure reasons can tell you why and what to do. The steps below walk you through the troubleshooting process, but you can also search for error codes and failure reasons.

1. Check the failure reason

Evervault provides human-readable failure reasons. Check these first to find out what's going on. If you need more information, move to the next step.

2. Check the transaction status

Check the transStatus code. Every authentication response includes this top-level value. It tells you what kind of outcome you're dealing with before you look at the specific reason.

If transStatus is N, U, or R, move to the next step. Otherwise, you hopefully have enough actionable information at this point.

3. Check the status reason

The transStatusReason code tells you why the failure occurred. The codes below are grouped into practical categories.

Request and data issues

Card and account status issues

ACS availability and technical issues

Frequency and decoupled authentication issues

Codes 15 through 18 (low, medium, high, and very high confidence) aren't failures. They indicate how confident the ACS is in its decision. For example, a transStatus of R with a transStatusReason of 18 means the ACS is very confident in the rejection.

You might have enough information at this point to resolve the issue, but if you're seeing any codes in the 80s, move to the next step.

4. Check card brand codes

Mastercard and Visa both use the 80s range for card brand codes, but the numbers don't mean the same thing. For example, code 81 is an accepted acquirer exemption from Mastercard but an ACS timeout from Visa. Always confirm the card brand before interpreting a code in this range.

Mastercard-specific codes (80–88)

Visa-specific codes (80–90)

Alternative configurations

These alternative configurations mostly relate to using redirects and the failOnChallenge flag. Both have somewhat niche use cases but can be useful in the right situations.

Using failOnChallenge

3DS supports frictionless and challenge flows. Frictionless authentication requires no interaction from the customer (and maintains liability shift). The frictionless flow automatically occurs when the issuer determines that a transaction is low-risk, eliminating the need for additional verification steps. This is a much smoother customer experience.

In challenge flows, customers are required to complete an authentication step to verify their identity. This is higher friction and usually requires a password, biometric authentication, etc.

The issuer decides on the flow, but Evervault provides an additional flag that can reduce friction when a challenge is requested. When you create 3DS sessions, you can set failOnChallenge to true. If a challenge is requested, Evervault automatically fails the 3DS session which prevents the challenge from ever being shown to the customer. This isn't technically a frictionless flow in terms of 3DS, but it does allow you to skip the challenge.

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

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.

3DS on mobile apps

Since the ThreeDSecure components in our React and JavaScript SDKs are built for the web, native mobile apps can instead complete 3DS by loading the challenge directly in a mobile webview. The hosted challenge page handles fingerprinting and the challenge window, and then redirects back to your app through a deep link after authentication is finalized.

1. Create the session and register a deep link

Create a 3DS session on your backend, and pass the session ID to your app. In your app, register a custom URL scheme or universal link (e.g., yourapp://3ds-complete) to receive the result.

2. Load the hosted challenge in an in-app webview

Open the hosted 3DS page in a webview, such as SFSafariViewController or WKWebView on iOS, and Chrome Custom Tabs or WebView on Android. Pass your deep link as the redirect parameter.

1https://3ds.evervault.com/?team=<TEAM_ID>&app=<APP_ID>&session=<SESSION_ID>&redirect=yourapp://3ds-complete

3. Handle the redirect and retrieve the 3DS credentials

When the session is finalized, the page redirects to your deep link with status and session appended (e.g., yourapp://3ds-complete?status=success&session=tds_abc123). Status can be success, failure, or error. Intercept the deep link, close the webview, and retrieve the session using the session ID. After a successful authentication is confirmed, you can forward the ECI and cryptogram to your PSP from your backend to finalize the payment.