3DS Web SDK Methods

Create Session

This method collects information from the browser on the background and sends it to the Basis Theory API, which then returns a newly created 3DS section.

Usage

import { BasisTheory3ds } from "@basis-theory/3ds-web";

const bt3ds = BasisTheory3ds("<API_KEY>");

const session = await bt3ds.createSession({ tokenId: "<TOKEN_ID>" });

Parameters

The createSession method accepts an object with the following attributes:

Attribute	Required	Type	Description
tokenId	false	string	The Basis Theory token id for the card token to be used
tokenIntentId	false	string	The Basis Theory token id for the card token intent to be used
skipMethodRequest	false	bool	Wether to skip performing a method request or not. Defaults to false
methodRequestMode	false	string	The mode to use for the method request. Accepts iframe or redirect. Defaults to iframe
challengeMode	false	string	The mode to use for performing a challenge. Accepts iframe or redirect. Defaults to iframe
pan	false	string	DEPRECATED The Basis Theory token id for the card token to be used

Note: Either tokenId or tokenIntentId is required.

Additional Details

Method Request

The Method Request allows the Access Control Server (ACS) to collect information directly about the customer's browser. By default, the Basis Theory 3DS SDK performs a method request during session creation.

If you want to skip this step, you can set the skipMethodRequest attribute to true.

Skipping the Method Request is not recommended, as it can potentially lower 3DS approval chances.

Modes

The method request and challenge are key stages in 3D Secure (3DS) where the browser directly interacts with the cardholder's bank's Access Control Server (ACS) to complete required tasks. By default, this interaction occurs within iframes, where the ACS URLs for the method request and challenge are loaded. During a challenge, users interact directly with the iframe.

However, because ACS URLs vary depending on the cardholder's issuing bank, websites with restrictive frame-src Content Security Policies (CSPs) may encounter issues performing these tasks. For such cases, we provide an alternative redirect mode.

In redirect mode:

• Instead of loading the ACS URLs in an iframe, a new window is opened.
• For method requests, the window automatically closes after data collection is complete.
• For challenges, the window closes upon successful challenge completion.

This approach ensures compatibility with restrictive CSPs while maintaining seamless operation for the end customer.

Return

The method returns an object with the following attributes:

Attribute	Type	Description
id	string	The created session id
cardBrand	string	The brand for the used card (i.e. Visa)

Start Challenge

This method initiates the 3DS challenge process, if it was deemed necessary during the 3DS authentication.

Usage

import { BasisTheory3ds } from "@basis-theory/3ds-web";

const bt3ds = BasisTheory3ds("<API_KEY>");

const challengeCompletion = await bt3ds.startChallenge({
  acsChallengeUrl: "https://some-challenge-url.com",
  acsTransactionId: "5236966c-62be-417b-8f66-dbec6d87911d",
  sessionId: "9289231e-2c0b-4f38-92fa-dec3c586d58b",
  threeDSVersion: "2.2.0",
});

Parameters

The startChallenge method takes in an object with the following attributes:

Attribute	Required	Type	Description
acsChallengeUrl	true	string	The URL for the challenge window. Available from the Authenticate endpoint response
acsTransactionId	true	string	The ACS transaction id. Available from the Authenticate endpoint response
sessionId	true	string	The created 3DS session id
threeDSVersion	true	string	The 3DS message version. Available from the Authenticate endpoint response
windowSize	false	string	The code for the pre-configured window size. See Challenge Window Sizes
timeout	false	number	The time in miliseconds to wait for challenge completion before considering it timed out. Defaults to 60000ms (1 minute)
mode	false	string	The mode to use for performing a challenge. Accepts iframe or redirect. Defaults to iframe

Return

The method returns a Promise, with the following attributes, that is only resolved once the customer completed or cancelled the challenge:

Attribute	Type	Description
id	string	The created session id

Challenge Window Sizes

WindowSize ID	Size
01	250px x 400px
02	390px x 400px
03	500px x 600px
04	600px x 400px
05	100% x 100%