NAV
Javascript

Get Started

Reference

Other Docs

More

Introduction

Basis Theory Elements are simple, secure, developer-friendly inputs that empower consumers to collect sensitive data from their users directly to Basis Theory certified vault.

Think about it as a portal that we open within your site that allows users to seamlessly tokenize information and never notice they are interacting with our technology. Here is how we make it possible:

Getting started

Before You Begin

If you don't have an account

To begin taking advantage of the Basis Theory platform, you’ll need to create an account and Tenant through our Portal.

If you have an account

Check out our API Reference documentation below, or go to our Getting Started section if you’re unsure of where to go next.

Install SDK

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>

You don't have to install Elements as a separate module or include additional script tags besides BasisTheory.js. It will dynamically load them from our secure domain, which enables us to keep the highest compliance standards (e.g. PCI compliance).

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

Content Security Policy

CSP

<head>
  <meta
    http-equiv="Content-Security-Policy"
    content="frame-src https://elements.basistheory.com; script-src https://js.basistheory.com"
  />
</head>

Trusted Types


trustedTypes.createPolicy("default", {
  createScriptURL: (input) => {
    if (new URL(input).origin === "https://js.basistheory.com") {
      return input;
    }
    return undefined;
  }
});

If you have a CSP deployed in your website, you must include the following directives:

If you are using Trusted Types, you must allow dynamic script loading from the https://js.basistheory.com origin. This should be done BEFORE initialization.

Common CSP Errors

The setup above is recommended to avoid errors similar to these:

Usage with TypeScript

In order to facilitate usage with TypeScript, an optional typings NPM module is available for installation.

NPM

npm install --save-dev @basis-theory/basis-theory-elements

Yarn

yarn add @basis-theory/basis-theory-elements --dev

Permissions

Permissions offer fine-grained control over your Application's access to different aspects of your token infrastructure. We suggest limiting the scope of your Application to the least amount possible, and to not share them across your internal services.

Permissions are associated with every Application and can be configured when you create an Application or update an Application.

Elements Applications only allow create permissions, removing any risk that your API keys are stolen and used to access data.

Permission Types

Permission Description Dependencies
token:create Create tokens in the vault N/A
card:create Create Atomic Card tokens token:create
bank:create Create Atomic Bank tokens token:create

Authentication

Elements use a specific type of Application key to allow access to the API. To create one, login into our Portal and create a new "Elements" Application with the permissions you require.

Limits

The Basis Theory API has rate limits applied to ensure the speed and consistency of our systems.

Error Codes

Error Code Meaning
429 Request has been rate limited

Initialize

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('test_1234567890', { elements: true });      
      // use BasisTheory.elements
    } catch (e) {
      // handle errors that could happen while loading elements script
    } 
  });  
</script>

Module

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

// In this context BasisTheory is a class
const bt = await new BasisTheory().init('test_1234567890', { elements: true });
// use bt.elements

After installing BasisTheory.js, simply initialize it with elements: true so it dynamically loads Elements module.

Element Types

Card Element

The "card" element type features a full credit card collector containing the following inputs:

Elements Instance

BasisTheory.elements

After initialization, Elements are available through BasisTheory instance.

Create Element

var cardElement = BasisTheory.elements.create('card', options);

This method returns a new instance of an element type.

Parameter Required Type Description
type true string Type of the element you want to create
options false CreateElementOptions Options for customizing the element

Create Element Options

CreateElementOptions provide a quick way to customize an Element before mounting it to your website.

Attribute Required Type Description
style false ElementStyle Object used to customize the element appearance

Mount Element

<div id="my-card"></div>

<script>
  cardElement.mount('#my-card')
</script>

This method attaches the element to the DOM, under a specific container.

Parameter Required Type Description
selector true string CSS selector that matches the container where your element will be mounted

Update Element

cardElement.update(options);

Updates the element options the element was initialized with. The values are deep-merged into the previous options.

Parameter Required Type Description
options false UpdateElementOptions Options for customizing the element

UpdateElementOptions

UpdateElementOptions provide a quick way to change an existing (mounted) Element appearance.

Attribute Required Type Description
style false ElementStyle Object used to customize the element appearance

Clear Element

cardElement.clear();

Clears the element input values.

Unmount Element

cardElement.unmount();

Safely removes the element from the DOM, stopping any further communication with it.

Element Events

var subscription = cardElement.on('event-type', (event) => {
  // handle event  
});

subscription.unsubscribe(); // stops listening to the event type

You can communicate with Elements by listening to events. When you subscribe to an event, you'll get back a Subscription that you can unsubscribe if/when it fits your workflow.

On Ready

cardElement.on('ready', () => {
  // handle ready event 
})

This event is triggered when the element has rendered and user is able to start interacting with it.

On Change

cardElement.on('change', (changeEvent) => {
  if (changeEvent.complete) {
    // enable submit button  
  } else {
    // disable submit button
    // present validation message
  }
})

This event is triggered whenever element's value(s) change. For example, if the user types data that doesn't change the state of a field between valid/invalid or empty/filled, you shouldn't expect the event to trigger.

Parameter Required Type Description
event true "change" The event type to listen to.
handler true function Callback function to be called when the event is fired. Takes in a ChangeEvent.

ChangeEvent

{
  "complete": false,
  "empty": false,
  "errors": [
    {...},
    {...}
  ]
}
Attribute Type Description
complete boolean If the element value is well-formed and is ready to be submitted.
empty boolean Whether the element is empty. Multi-input Elements will be empty only if all inputs are.
errors array Array of FieldError.

FieldError

{
  "targetId": "cardNumber",
  "type": "invalid"
}
Attribute Type Description
targetId string Input id that triggered the error. Values vary per element type.
type "invalid" or "incomplete" Type of the error.

On Focus

cardElement.on('focus', (focusEvent) => {

})

Triggered when an element input is focused.

Parameter Required Type Description
event true "focus" The event type to listen to.
handler true function Callback function to be called when the event is fired. Takes in a FocusEvent.

FocusEvent

{
  "targetId": "cardNumber"  
}
Attribute Type Description
targetId string Input id that triggered the event. Values vary per element type.

On Blur

cardElement.on('blur', (blurEvent) => {

})

Triggered when an element input focus is lost.

Parameter Required Type Description
event true "blur" The event type to listen to.
handler true function Callback function to be called when the event is fired. Takes in a BlurEvent.

BlurEvent

{
  "targetId": "cardNumber"  
}
Attribute Type Description
targetId string Input id that triggered the event. Values vary per element type.

On Keydown

cardElement.on('keydown', (keydownEvent) => {

})

Triggered when user hits a special key inside an element input.

Parameter Required Type Description
event true "keydown" The event type to listen to.
handler true function Callback function to be called when the event is fired. Takes in a KeydownEvent.

KeydownEvent

{
  "targetId": "cardNumber",
  "key": "Enter",
  "ctrlKey": false,
  "altKey": false,
  "shiftKey": false,
  "metaKey": false
}
Attribute Type Description
targetId string Input targetId that triggered the event. Values vary per element type.
key Escape or Enter Key pressed by the user.
ctrlKey boolean Flag indicating control key was pressed when the event occurred.
altKey boolean Flag indicating alt key was pressed when the event occurred.
shiftKey boolean Flag indicating shift key was pressed when the event occurred.
metaKey boolean Flag indicating meta key was pressed when the event occurred.

Element Style

var cardElement = BasisTheory.elements.create('card', {
  style: {
    fonts: [
      "https://fonts.googleapis.com/css2?family=Source+Sans+Pro:ital,[email protected],200;0,300;0,400;0,600;0,700;0,900;1,200;1,300;1,400;1,600;1,700;1,900&display=swap"
    ],
    base: {
      color: "#fff",
      fontWeight: 500,
      fontFamily: "'Source Sans Pro'",
      fontSize: "16px",
      fontSmooth: "antialiased",
      "::placeholder": {
        color: "#6b7294"
      },
      invalid: {
        color: "#ffc7ee"
      },
      complete: {
        color: "#1ad1db"
      }
    }
  }
})

Elements are styled through the ElementStyle object, which maps state variants and miscellaneous.

Attribute Required Type Description
fonts false array Array of Google Fonts URLs
base false object Base variant style - all other variant styles inherit from this one
complete false object Variant style applied when the element input has valid value
empty false object Variant style applied when the element input has no value
invalid false object Variant style applied when the element input has invalid value

You can customize the following pseudo-classes and pseudo-elements inside each variant using a nested object:

Here is a complete list of the supported CSS properties:

Store Credit Card

BasisTheory.elements.storeCreditCard({
  card: cardElement,
  billingDetails: {
    name: 'Fiona Theory'  
  }
}).then((token) => {
  console.log(token.id); // token to store
  console.log(JSON.stringify(token.card)); // redacted card data
});

Allows secure submission and tokenization of a card element. Returns a Promise that resoles to the tokenized card data. See CardModel for the resolved value type.

Internally, BasisTheory.elements.storeCreditCard calls Create Atomic Card API.

You can fetch this same data later with Get an Atomic Card API.

storeCreditCard Errors

BasisTheory.elements.storeCreditCard(...).catch(error => {
  // handle error
});

In case storeCreditCard throws an error, that could be related to client-side validation or an unaccepted request from the server.

Attribute Type Scope Description
validation array client Array of FieldError, in case of client-side error.
data object server Response body sent from the server.
status number both Response HTTP status or -1 if the request never left the client (i.e. connection issues)
Javascript