Web 3DS

Enterprise

3D Secure is an Enterprise feature. Contact support@basistheory.com to request access.

Browser environments only — WebView embedding is not supported

The 3DS Web SDK is designed for real browser environments. Embedding it inside a mobile WebView (React Native WebView, iOS WKWebView, Android WebView) is not supported and will cause 3DS challenge failures. WebViews intercept cross-origin navigations and enforce third-party cookie restrictions that prevent the ACS challenge-notification flow from completing, resulting in silent timeouts (transStatusReason: 14) regardless of whether the cardholder completes the challenge. For mobile app integrations, use the native SDKs instead: 3DS Mobile SDK (iOS / Android), or React Native 3DS.

web-threeds

web-threeds

Loading Stars

Loading Contributors

See it in GitHub

The Basis Theory web-threeds package makes it easy to start a 3DS transaction from the browser.

Get started with our guide or continue reading the reference docs.

Before You Begin

The web-threeds package uses methodFrameContainer and challengeFrameContainer as pre-defined HTML element IDs for its operation. Avoid creating elements with the same id as they could be modified by the SDK.

This SDK requires the use of an API Key associated with a Public Application.

To create one, login into our Portal and create a new "Public" Application with the 3ds:session:create permission.

Installation

npm

npm install --save @basis-theory/web-threeds

yarn

yarn add @basis-theory/web-threeds

CDN

<!-- Including this tag will export a global/window "BasisTheory3ds" method -->
<script src="https://3ds.basistheory.com/web-threeds/index.js"></script>
<!-- or -->
<script src="https://3ds.basistheory.com/web-threeds/v0.1/index.js"></script>

Initialization

ES Module

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

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

CDN

  <script>
    // you can initialize it wherever it suits your workflow best
    // here we are waiting for the window to load, to make sure BasisTheory3ds method
    // has been injected in the window variable
    window.addEventListener("load", async () => {
      try {
        // get the SDK methods onto a variable
        const bt3ds = BasisTheory3ds("<API_KEY>");
      } catch (e) {
        // handle errors that could happen during initialization
      }
    });
  </script>

Initialization Parameters

Parameter	Required	Type	Description
apiKey	true	string	The API Key used to identify the Application
options	false	object	Options for customizing the SDK usage

Initialization Options

Usage

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

const bt3ds = BasisTheory3ds("<API_KEY>", {
  apiBaseUrl: 'https://some-custom-url',
});

Attributes

Attribute	Required	Type	Description
apiBaseUrl	false	string	The base URL for the Basis Theory API, if using a mock API
disableTelemetry	false	boolean	Disables telemetry. Defaulted to false