JavaScript Elements SDK

JavaScript Elements SDK

basis-theory-js

Loading Stars

Loading Contributors

The Basis Theory JavaScript SDK makes it easy to build secure web applications that collect or reveal sensitive data using Elements.

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

Before You Begin

This SDK requires the use of an API Key associated with a Public Application, which only allows token:create or token:update permissions to mitigate the risk that these API keys may be publicly exposed within your frontend applications.

To create one, login into our Portal and create a new "Public" Application with the permissions you require.

Considerations

Basis Theory Javascript SDK uses conventional camel case for most methods and converts these properties to snake case when sending requests to the API. One notable exception to this is the Tokenize method which uses snake case for the request body.

Installation

To install BasisTheory.js you can choose either our ES module or CDN hosted bundle through a script tag.

npm

npm install --save @basis-theory/basis-theory-js

yarn

yarn add @basis-theory/basis-theory-js

CDN

<!-- Including this tag will export a global/window "BasisTheory" variable -->
<script src="https://js.basistheory.com"></script>

The Basis Theory JS SDK >1.77.0 is not compatible with Create React App v5.0.0 or above due to a known issue.

Initialization

Initialize BasisTheory with elements: true to dynamically loads Elements module.

ES Module

import { BasisTheory } from "@basis-theory/basis-theory-js";

// In this context BasisTheory is a class
const bt = await new BasisTheory().init("<API_KEY>", { elements: true });
// use Elements

CDN

<script>
  // you can initialize it wherever it suits your workflow best
  // here we are waiting for the window to load, to make sure BasisTheory instance
  // has been injected in the window variable
  window.addEventListener("load", async () => {
    try {
      // global/window variable BasisTheory is an instance, but requires initialization
      await BasisTheory.init("<API_KEY>", { elements: true });
      // use Elements
    } catch (e) {
      // handle errors that could happen while loading elements script
    }
  });
</script>

Parameter	Required	Type	Description
apiKey	true	string	The API Key used to identify an Application.
options	false	BasisTheoryInitOptions	Options for initializing the BasisTheory instance.

Basis Theory Init Options

Attribute	Required	Type	Description
elements	false	boolean	Boolean used to indicate whether the BasisTheory instance will have Elements capabilities.

Elements are meant to be used in browser environments only. If you installed BasisTheory.js as a module, make sure the instance that loads elements runs on the browser-side code.

If you try to to use any Elements feature before calling BasisTheory.init, or before its Promise has been fulfilled, you will get an error.

Usage with TypeScript

Starting at 1.14.0, BasisTheory.js bundles all TypeScript definitions for Elements features. You don't have to take any extra steps in order to use it.