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>

Content Security Policy

If your application enforces a Content Security Policy, add these sources to the matching directives in the policy you already serve, so the SDK can load, call the API, and mount its iframes:

frame-src   https://3ds.basistheory.com;
script-src  https://3ds.basistheory.com;
connect-src https://api.basistheory.com https://http-intake.logs.datadoghq.com;

Merge them into your existing policy rather than publishing a second one alongside it. A page can carry more than one policy, and a resource has to be allowed by every one of them, so a policy listing only the sources above would block your application's own scripts, connections, and frames. A second policy also cannot loosen the one you already send. See Content Security Policy Level 3 for how multiple policies combine.

For an application whose existing sources are 'self', the merged directives look like this:

Content-Security-Policy: frame-src 'self' https://3ds.basistheory.com; script-src 'self' https://3ds.basistheory.com; connect-src 'self' https://api.basistheory.com https://http-intake.logs.datadoghq.com

Directive	Source to add	Why it is needed
frame-src	https://3ds.basistheory.com	The SDK mounts the method request and challenge iframes from this host
script-src	https://3ds.basistheory.com	Required only when loading the SDK from the CDN. Omit it if you install from npm and bundle the SDK yourself
connect-src	https://api.basistheory.com	The SDK calls the 3DS Sessions API from the browser
connect-src	https://http-intake.logs.datadoghq.com	SDK telemetry. Omit it if you initialize with disableTelemetry: true. Blocking this host does not break 3DS, but it logs CSP violations and reduces the diagnostics available to support

If your policy sets style-src-attr, style-src, or default-src without 'unsafe-inline', the browser blocks the inline style the SDK uses to hide its method request container and reports a violation. That container holds a zero-sized iframe, so nothing becomes visible and authentication is unaffected.

ACS domains do not need to be allowlisted

ACS URLs vary by the cardholder's issuing bank. This does not require a wildcard frame-src, because your page never frames the ACS directly.

In iframe mode, the default, the only frames your page loads are the two pages served from https://3ds.basistheory.com. Each of those pages loads its ACS URL in an iframe of its own:

your-checkout-page.com                                        (your CSP applies here)
├── iframe  https://3ds.basistheory.com/pages/method.html
│   └── iframe  https://acs.issuing-bank.example/...          (framed by our page)
└── iframe  https://3ds.basistheory.com/pages/challenge.html
    └── iframe  https://acs.issuing-bank.example/...          (framed by our page)

A Content Security Policy applies to the document that declares it and is not inherited by cross-origin child documents. Your frame-src restricts the frames your page loads, so it never has to name the issuer's domain.

This applies to @basis-theory/web-threeds v0.2.0 and later. Earlier versions load the ACS URL directly from your page and need a broader frame-src.

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