NAV
shell html javascript--node typescript
Go to Portal

Getting Started

API Reference

Modules

Introduction

The Basis Theory API is organized around REST. Our API is built with a predictable resource-oriented structure, uses JSON-encoded requests and responses, follows standard HTTP verbs/responses, and uses industry standard authentication.

You are able to create different tenants within your Basis Theory account to enable you to segment your test environments from your core production data. Tenants serve as a logical grouping for each of your systems to interact with Basis theory without affecting each other.

What is Basis Theory?

Our software becomes a core part of your infrastructure enabling you to quickly encrypt, tokenize, and store any payload securely. Your token infrastructure can be used to protect data at rest, as it passes between your own internal systems, or how it's permissioned and shared with third parties.

Getting started

Before you begin

If you don't have an account

Currently, Basis Theory is in private beta, you can join our waitlist at https://basistheory.com and we will let you know when we are accepting new applicants.

To begin taking advantage of the Basis Theory platform, you’ll need to create an account and tenant through our Portal. This will enable you to manage your token data, create new applications, and authenticate to our API.

If you have an account

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

Authentication

Authentication Example:

curl "https://api.basistheory.com" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Make sure to replace key_N88mVGsp3sCXkykyN2EFED with your API key.

Basis Theory uses API keys to allow access to the API.

Basis Theory expects for the API key to be included in all API requests to the server in a header that looks like the following:

X-API-KEY: key_N88mVGsp3sCXkykyN2EFED

Request correlation

Correlation ID Example:

curl "https://api.basistheory.com" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "bt-trace-id: aa5d3379-6385-4ef4-9fdb-ca1341572153"

Basis Theory utilizes Correlation IDs to assist with request tracing, logging, and debugging.

All API endpoints accepts a client-provided Correlation ID if sent with the bt-trace-id HTTP header within POST, PUT, PATCH, DELETE methods.

If a bt-trace-id Correlation ID is not provided by the client, a new Correlation ID will be generated by the Basis Theory API.

Pagination

Pagination Request Example:

curl "https://api.basistheory.com/applications?page=2&size=10" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Pagination Response Example:

{
  "pagination": {
    "total_items": 924,
    "page_number": 2,
    "page_size": 10,
    "total_pages": 93
  },
  "data": [
    {...},
    {...},
    {...}
  ]
}

All List endpoints support pagination to allow bulk fetching multiple items. Each List endpoint shares a common response structure. Examples of these requests can be seen in List Applications, List Tokens, and List Atomic Cards

Query Parameters

Parameter Required Type Default Description
page false integer 1 Page number of the results to return
size false integer 20 Number of results per page to return. Maximum size of 100 results.

Response Schema

Attribute Type Description
pagination object Pagination metadata
data array Query results of the request. See list endpoint resource for response schema definition

Pagination Response Object

Attribute Type Description
total_items integer Total number of items in the tenant
page_number integer Current page number. Should match page query parameter.
page_size integer The size of each page. Should match size query parameter.
total_pages integer The total number of pages.

Errors

{
  "errors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "string"
}

Response Schema

Attribute Type Description
errors.{property} array An array of human readable error messages returned per request {property}
status integer HTTP status code of the responses

Error Codes

Error Code Meaning
400 Invalid request body.
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 Request entity was not found
500 Something went wrong on Basis Theory's side

Permissions

Permissions are 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 applications.

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

Every API endpoint will document the required permissions needed to perform the operation against the endpoint.

Permission Types

Permission Description Application Types Dependencies
token:read Read tokens from the vault server_to_server N/A
token:write Write tokens to the vault public, elements, server_to_server N/A
application:read Read applications management N/A
application:write Create, edit, delete, and regenerate API keys for applications management N/A
card:read Read atomic card tokens server_to_server token:read
card:create Create atomic card tokens public, elements, server_to_server token:write
card:update Update atomic card tokens server_to_server token:write
card:delete Delete atomic card tokens server_to_server token:write

List Permissions

List Permissions Request Example:

curl "https://api.basistheory.com/permissions" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Permissions Response Example:

[
  {
    "type": "card:read",
    "description": "Read Payment Card tokens",
    "application_types": [
      "server_to_server"
    ],
    "dependencies": [
      "token:read"
    ]
  }, 
  {...},
  {...}
]

GET https://api.basistheory.com/permissions

Response Schema

Attribute Type Description
type string Permission type referenced by Basis Theory API endpoints
description string Description of the permission
application_types array List of application types that can assign the permission
dependencies array List of downstream permission types which are required for this permission type

Response Messages

Code Description
200 Permissions successfully retrieved
401 A missing or invalid X-API-KEY was provided

Tenants

Tenants provide a way to logically group your applications and tokens. Common use cases for tenants may be per environment such as development, QA, and production or to isolate business domains from each other. Tenant data is isolated from each other unless explicitely shared.

Get a Tenant

Get a Tenant Request Example:

curl "https://api.basistheory.com/tenants/self" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Tenant Response Example:

{
  "id": "f88da999-b124-4a14-acde-cbc121444f14",
  "owner_id": "97cec6e8-a143-4fb4-9ab0-cf7e49242d21",
  "name": "My Tenant",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

GET https://api.basistheory.com/tenants/self

Retrieves the tenant associated with the provided X-API-KEY.

Permissions

tenant:read

Response Schema

Attribute Type Description
id string Unique identifier of the tenant
owner_id string The user ID which owns the tenant
name string The name of the tenant
created_at string Created date of the application in ISO 8601 format
modified_at string Last modified date of the application in ISO 8601 format

Response Messages

Code Description
200 Tenant successfully retrieved
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 The tenant was not found

Update Tenant

Update Tenant Request Example:

curl "https://api.basistheory.com/tenants/self" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "PUT"
  -D '{
    "name": "My Example Tenant"
  }'

Update Tenant Response Example:

{
  "id": "f88da999-b124-4a14-acde-cbc121444f14",
  "owner_id": "97cec6e8-a143-4fb4-9ab0-cf7e49242d21",
  "name": "My Example Tenant",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

PUT https://api.basistheory.com/tenants/self

Update the tenant associated with the provided X-API-KEY.

Permissions

application:update

Request Schema

Attribute Required Type Default Description
name true string null The name of the tenant. Has a maximum length of 200

Response Schema

Attribute Type Description
id string Unique identifier of the tenant
owner_id string The user ID which owns the tenant
name string The name of the tenant
created_at string Created date of the application in ISO 8601 format
modified_at string Last modified date of the application in ISO 8601 format

Response Messages

Code Description
200 Tenant successfully updated
400 Invalid request body. See Errors response for details
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 The tenant was not found

Delete Tenant

Delete Tenant Request Example:

curl "https://api.basistheory.com/tenants/self" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "DELETE"

DELETE https://api.basistheory.com/tenants/self

Delete the tenant associated with the provided X-API-KEY.

Permissions

tenant:write

Response Messages

Code Description
204 Tenant successfully deleted
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 The tenant was not found

Applications

Your ability to authenticate to the API is granted by creating Applications, each application type has differnet usages to create the most fine-grained control over your tokens and infrastructure possible. Below, we describe each application type and their usages.

Application Types

Name Type Description
Server-to-Server server_to_server Used for tokenizing, retrieving, and decrypting data within backend services where the API key can be secured
Public public Used for tokenizing data directly within your mobile or browser application
Elements elements Used for tokenizing data with the Basis Theory Elements module
Management management Used for managing all aspects of your token infrastructure such as creating an applications

Create Application

Create Application Request Example:

curl "https://api.basistheory.com/applications" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "POST"
  -D '{
    "name": "My Example App",
    "type": "server_to_server",
    "permissions": [
      "card:create",
      "card:read",
      "token:write",
      "token:read"
    ]
  }'

Create Application Response Example:

{
  "id": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Example App",
  "key": "key_FZ8RmaxoGc73lbmF2cpmUJ",
  "type": "server_to_server",
  "created_at": "2020-09-15T15:53:00+00:00",
  "permissions": [
    "card:create",
    "card:read",
    "token:write",
    "token:read"
  ]
}

POST https://api.basistheory.com/applications

Create a new application for the tenant.

Permissions

application:write

Request Schema

Attribute Required Type Default Description
name true string null The name of the application. Has a maximum length of 200
type true string null Application of the application
permissions false array [] Perimissions for the application

Response Schema

Attribute Type Description
id string Unique identifier of the application which can be used to get an application
tenant_id string The tenant ID which owns the application
name string The name of the application
key string The API key which should be used for authenticating against Basis Theory API endpoints
type string Application type of the application
created_at string Created date of the application in ISO 8601 format
permissions array List of permissions for the application

Response Messages

Code Description
201 Application successfully created
400 Invalid request body. See Errors response for details
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions

List Applications

List Applications Request Example:

curl "https://api.basistheory.com/applications" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Applications Response Example:

{
  "pagination": {...}
  "data": [
    {
      "id": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "name": "My Example App",
      "type": "server_to_server",
      "created_at": "2020-09-15T15:53:00+00:00",
      "modified_at": "2021-03-01T08:23:14+00:00",
      "permissions": [
        "card:create",
        "card:read",
        "token:write",
        "token:read"
      ]
    },
    {...},
    {...}
  ]
}

List Applications by IDs Request Example:

curl "https://api.basistheory.com/applications?id=72ef3d62-b7de-4b5f-8aa2-b9db06c291cb&id=3b235ac3-83ea-49c5-8c42-05ba3cbd17d1" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

GET https://api.basistheory.com/applications

Get a list of applications for the tenant.

Permissions

application:read

URI Parameters

Parameter Required Type Default Description
id false array [] An optional list of application ID's to filter the list of applications by

Response Schema

Returns the Pagination schema. The data attribute in the response contains an array of applications with the following schema:

Attribute Type Description
id string Unique identifier of the application which can be used to get an application
tenant_id string The tenant ID which owns the application
name string The name of the application
type string Application type of the application
created_at string Created date of the application in ISO 8601 format
modified_at string Last modified date of the application in ISO 8601 format
permissions array List of permissions for the application

Response Messages

Code Description
200 Applications successfully retrieved
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions

Get an Application

Get an Application Request Example:

curl "https://api.basistheory.com/applications/fe1f9ba4-474e-44b9-b949-110cdba9d662" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Application Response Example:

{
  "id": "fe1f9ba4-474e-44b9-b949-110cdba9d662",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Management App",
  "type": "management",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_at": "2021-03-01T08:23:14+00:00",
  "permissions": [
    "application:read",
    "application:write"
  ]
}

GET https://api.basistheory.com/applications/{id}

Get an application by ID in the tenant.

Permissions

application:read

URI Parameters

Parameter Required Type Default Description
id true string null The ID of the application

Response Schema

Attribute Type Description
id string Unique identifier of the application which can be used to get an application
tenant_id string The tenant ID which owns the application
name string The name of the application
type string Application type of the application
created_at string Created date of the application in ISO 8601 format
modified_at string Last modified date of the application in ISO 8601 format
permissions array List of permissions for the application

Response Messages

Code Description
200 Application successfully retrieved
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 The application was not found

Get an Application by Key

Get an Application Request Example:

curl "https://api.basistheory.com/applications/key" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Application Response Example:

{
  "id": "fe1f9ba4-474e-44b9-b949-110cdba9d662",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Management App",
  "type": "management",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_at": "2021-03-01T08:23:14+00:00",
  "permissions": [
    "application:read",
    "application:write"
  ]
}

GET https://api.basistheory.com/applications/key

Get an application by key in the tenant. Will use the X-API-KEY header to lookup the application.

Permissions

application:read

Response Schema

Attribute Type Description
id string Unique identifier of the application which can be used to get an application
tenant_id string The tenant ID which owns the application
name string The name of the application
type string Application type of the application
created_at string Created date of the application in ISO 8601 format
modified_at string Last modified date of the application in ISO 8601 format
permissions array List of permissions for the application

Response Messages

Code Description
200 Application successfully retrieved
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 The application was not found

Update Application

Update Application Request Example:

curl "https://api.basistheory.com/applications/fb124bba-f90d-45f0-9a59-5edca27b3b4a" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "PUT"
  -D '{
    "name": "My Example App",
    "permissions": [
      "application:read",
      "application:write"
    ]
  }'

Update Application Response Example:

{
  "id": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Example App",
  "type": "server_to_server",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_at": "2021-03-01T08:23:14+00:00",
  "permissions": [
    "application:read",
    "application:write"
  ]
}

PUT https://api.basistheory.com/applications/{id}

Update an application by ID in the tenant.

Permissions

application:write

URI Parameters

Parameter Required Type Default Description
id true string null The ID of the application

Request Schema

Attribute Required Type Default Description
name true string null The name of the application. Has a maximum length of 200
permissions false array [] Perimissions for the application

Response Schema

Attribute Type Description
id string Unique identifier of the application which can be used to get an application
tenant_id string The tenant ID which owns the application
name string The name of the application
type string Application type of the application
created_at string Created date of the application in ISO 8601 format
modified_at string Last modified date of the application in ISO 8601 format
permissions array List of permissions for the application

Response Messages

Code Description
200 Application successfully updated
400 Invalid request body. See Errors response for details
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 The application was not found

Regenerate API Key

Regenerate Application API Key Request Example:

curl "https://api.basistheory.com/applications/fb124bba-f90d-45f0-9a59-5edca27b3b4a/regenerate" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "POST"

Regenerate Application API Key Response Example:

{
  "id": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "key": "key_FZ8RmaxoGc73lbmF2cpmUJ",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

POST https://api.basistheory.com/applications/{id}/regenerate

Regenerate the API key for an application.

Permissions

application:write

URI Parameters

Parameter Required Type Default Description
id true string null The ID of the application

Response Schema

Attribute Type Description
id string Unique identifier of the application which can be used to get an application
key string The API key which should be used for authenticating against Basis Theory API endpoints
modified_at string Last modified date of the application in ISO 8601 format

Response Messages

Code Description
200 Application API Key successfully regenerated
400 Invalid request body. See Errors response for details
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 The application was not found

Delete Application

Delete Application Request Example:

curl "https://api.basistheory.com/applications/fb124bba-f90d-45f0-9a59-5edca27b3b4a" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "DELETE"

DELETE https://api.basistheory.com/applications/{id}

Delete an application by ID in the tenant.

Permissions

application:write

URI Parameters

Parameter Required Type Default Description
id true string null The ID of the application

Response Messages

Code Description
204 Application successfully deleted
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 The application was not found

Tokens

Token Types

Name Type Description
Token token Generic token type. This is the default token type if none is provided when creating a new token
Card card Atomic card token type
Bank bank Atomic bank token type

Create Token

Create Token Request Example:

curl "https://api.basistheory.com/tokens" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "POST"
  -D '{
    "type": "token",
    "data": "ebSG3IohNmg5gTOjN2HBwBbhjDZ6BY3fCWZJfXSucVMfQ+7YNMXQYrPuRSXgSkhuTMYS+BNfVUur4qZSvUbgCA==",
    "metadata": {
      "NonSensitiveField": "Non-Sensitive Value"
    }
    "encryption": {
      "cek": {
        "key": "JLrtGbYSN5/dbqdKtLVG8tHu3QefcZnKsFOPBBXlXcG4zL9US01mW2MqZs6Px4ckSQM8CrRakwLKilrQ0f37Iw==",
        "alg": "AES"
      },
      "kek": {
        "key": "vpXn45HnsoQPR1q8ptngmPvPaqIDJ4vO+FFyQclglePCt8d1SyTDJU0T+F54T7GnAz7vz5OKsjgsFNo9lVB3UA==",
        "alg": "RSA"
      }
    }
  }'

Create Token Response Example:

{
  "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "token",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "metadata": {
    "NonSensitiveField": "Non-Sensitive Value"
  }
}

Create Token Data Examples:

{
  "data": "RandomString"
}
{
  "data": true
}
{
  "data": [1, 2, 3]
}
{
  "data": { 
    "string_field": "RandomString",
    "int_field": 3,
    "bool_field": false,
    "array_field": [1, 2, 3]
    "object_field": {...} 
  }
}

POST https://api.basistheory.com/tokens

Create a new token for the tenant.

Permissions

token:write

Request Schema

Attribute Required Type Default Description
type false string token Token type of the token
data true any null Token data
metadata false any null Non-sensitive token metadata
encryption false object null Encryption metadata for an encrypted token data value

Encryption Object Schema

Attribute Required Type Default Description
cek false object null Content encryption key
kek false object null Key encryption key

Encryption Key Object Schema

Attribute Required Type Default Description
key false string null Encryption key or key identifier
alg false string null Encryption algorithm (e.g. AES, RSA, etc)

Response Schema

Attribute Type Description
id string Unique identifier of the token which can be used to get a token
tenant_id string The tenant ID which owns the token
type string Token type
created_by string The application ID which created the token
created_at string Created date of the token in ISO 8601 format
metadata any The metadata provided when creating the token

Response Messages

Code Description
201 Token successfully created
400 Invalid request body. See Errors response for details
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions

List Tokens

List Tokens Request Example:

curl "https://api.basistheory.com/tokens" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Tokens Response Example:

{
  "pagination": {...}
  "data": [
    {
      "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
      "type": "token",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "data": "ebSG3IohNmg5gTOjN2HBwBbhjDZ6BY3fCWZJfXSucVMfQ+7YNMXQYrPuRSXgSkhuTMYS+BNfVUur4qZSvUbgCA==",
      "metadata": {
        "NonSensitiveField": "Non-Sensitive Value"
      }
      "encryption": {
        "cek": {
          "key": "JLrtGbYSN5/dbqdKtLVG8tHu3QefcZnKsFOPBBXlXcG4zL9US01mW2MqZs6Px4ckSQM8CrRakwLKilrQ0f37Iw==",
          "alg": "AES"
        },
        "kek": {
          "key": "vpXn45HnsoQPR1q8ptngmPvPaqIDJ4vO+FFyQclglePCt8d1SyTDJU0T+F54T7GnAz7vz5OKsjgsFNo9lVB3UA==",
          "alg": "RSA"
        }
      },
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2021-03-01T08:23:14+00:00"
    },
    {...},
    {...}
  ]
}

List Tokens by Type Request Example:

curl "https://api.basistheory.com/tokens?type=card" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

GET https://api.basistheory.com/tokens

Get a list of tokens for the tenant.

Permissions

token:read

URI Parameters

Parameter Required Type Default Description
type false string null An optional token type to filter the list of tokens by

Response Schema

Returns the Pagination schema. The data attribute in the response contains an array of tokens with the following schema:

Attribute Type Description
id string Unique identifier of the token which can be used to get a token
tenant_id string The tenant ID which owns the token
type string Token type
data any The data provided when creating the token
metadata any The metadata provided when creating the token
encryption any The encryption data provided when creating the token
created_by string The application ID which created the token
created_at string Created date of the token in ISO 8601 format

Response Messages

Code Description
200 Tokens successfully retrieved
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions

Get a Token

Get a Token Request Example:

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Token Response Example:

{
  "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
  "type": "token",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "data": "ebSG3IohNmg5gTOjN2HBwBbhjDZ6BY3fCWZJfXSucVMfQ+7YNMXQYrPuRSXgSkhuTMYS+BNfVUur4qZSvUbgCA==",
  "metadata": {
    "NonSensitiveField": "Non-Sensitive Value"
  }
  "encryption": {
    "cek": {
      "key": "JLrtGbYSN5/dbqdKtLVG8tHu3QefcZnKsFOPBBXlXcG4zL9US01mW2MqZs6Px4ckSQM8CrRakwLKilrQ0f37Iw==",
      "alg": "AES"
    },
    "kek": {
      "key": "vpXn45HnsoQPR1q8ptngmPvPaqIDJ4vO+FFyQclglePCt8d1SyTDJU0T+F54T7GnAz7vz5OKsjgsFNo9lVB3UA==",
      "alg": "RSA"
    }
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2021-03-01T08:23:14+00:00"
}

GET https://api.basistheory.com/tokens/{id}

Get a token by ID in the tenant.

Permissions

token:read

URI Parameters

Parameter Required Type Default Description
id true string null The ID of the token

Response Schema

Attribute Type Description
id string Unique identifier of the token which can be used to get a token
tenant_id string The tenant ID which owns the token
type string Token type
data any The data provided when creating the token
metadata any The metadata provided when creating the token
encryption any The encryption data provided when creating the token
created_by string The application ID which created the token
created_at string Created date of the token in ISO 8601 format

Response Messages

Code Description
200 Tokens successfully retrieved
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 The token was not found

Delete Token

Delete Token Request Example:

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "DELETE"

DELETE https://api.basistheory.com/tokens/{id}

Delete a token by ID in the tenant.

Permissions

token:write

URI Parameters

Parameter Required Type Default Description
id true string null The ID of the token

Response Messages

Code Description
204 Token successfully deleted
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 The token was not found

Atomic Cards

Create Atomic Card

Create Atomic Card Request Example:

curl "api.basistheory.com/atomic/cards" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "POST"
  -D '{
    "card": {
      "number": "4242424242424242",
      "expiration_month": 12,
      "expiration_year": 2025,
      "cvc": "123"
    },
    "billing_details": {
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "555-123-4567",
      "address": {
        "line1": "111 Test St.",
        "line2": "Apt 304",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94141",
        "country": "US"
      }
    }
  }'

Create Atomic Card Response Example:

{
  "id": "c1e565009-1984-4638-8fca-dce8a82cc2af",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "card",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "card": {
    "number": "XXXXXXXXXXXX4242",
    "expiration_month": 12,
    "expiration_year": 2025
  }
}

POST https://api.basistheory.com/atomic/cards

Create a new atomic card for the tenant.

Permissions

card:create token:write

Request Schema

Attribute Required Type Default Description
card true card null Card object
billing_details false billing details null Billing details object

Card Object Schema

Attribute Required Type Default Description
number true string null The card number without any separators
expiration_month true integer null Two-digit number representing the card's expiration month
expiration_year true integer null Four-digit number representing the card's expiration year

Billing Details Object Schema

Attribute Required Type Default Description
name false string null The cardholder or customer's full name
email false string null The cardholder or customer's email address
phone false string null The cardholder or customer's phone number
address false address null The cardholder or customer's address

Address Object Schema

Attribute Required Type Default Description
line1 false string null Address line 1 (Street address / PO Box / Company name)
line2 false string null Address line 2 (Apartment / Suite / Unit / Building)
city false string null City / District / Suburb / Town / Village
state false string null State / County / Province / Region
postal_code false string null Zip or postal code
country false string null Two-character ISO country code (e.g. US)

Response Schema

Attribute Type Description
id string Unique identifier of the token which can be used to get an atomic card
tenant_id string The tenant ID which owns the card
type string Card token type
created_by string The application ID which created the atomic card
created_at string Created date of the application in ISO 8601 format
card card Masked card object

Response Messages

Code Description
201 Atomic card successfully created
400 Invalid request body. See Errors response for details
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions

List Atomic Cards

List Atomic Cards Request Example:

curl "api.basistheory.com/atomic/cards" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Atomic Cards Response Example:

{
  "pagination": {...}
  "data": [
    {
      "id": "c1e565009-1984-4638-8fca-dce8a82cc2af",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "type": "card",
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2020-09-15T15:53:00+00:00",
      "card": {
        "number": "XXXXXXXXXXXX4242",
        "expiration_month": 12,
        "expiration_year": 2025
      }
    },
    {...},
    {...}
  ]
}

GET https://api.basistheory.com/atomic/cards

Get a list of atomic cards for the tenant.

Permissions

card:read token:read

Response Schema

Returns the Pagination schema. The data attribute in the response contains an array of tokens with the following schema:

Attribute Type Description
id string Unique identifier of the token which can be used to get an atomic card
tenant_id string The tenant ID which owns the card
type string Card token type
created_by string The application ID which created the atomic card
created_at string Created date of the application in ISO 8601 format
card card Masked card object

Response Messages

Code Description
200 Atomic cards successfully retrieved
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions

Get an Atomic Card

Get Atomic Card Request Example:

curl "api.basistheory.com/atomic/cards/c1e565009-1984-4638-8fca-dce8a82cc2af" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Atomic Card Response Example:

{
  "id": "c1e565009-1984-4638-8fca-dce8a82cc2af",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "card",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "card": {
    "number": "XXXXXXXXXXXX4242",
    "expiration_month": 12,
    "expiration_year": 2025
  }
}

GET https://api.basistheory.com/atomic/cards/{id}

Get an atomic card by ID in the tenant.

Permissions

card:read token:read

URI Parameters

Parameter Required Type Default Description
id true string null The ID of the atomic card

Response Schema

Attribute Type Description
id string Unique identifier of the token which can be used to get an atomic card
tenant_id string The tenant ID which owns the card
type string Card token type
created_by string The application ID which created the atomic card
created_at string Created date of the application in ISO 8601 format
card card Masked card object

Response Messages

Code Description
200 Atomic card successfully retrieved
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 The atomic card was not found

Delete Atomic Card

Delete Token Request Example:

curl "api.basistheory.com/atomic/cards/c1e565009-1984-4638-8fca-dce8a82cc2af" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "DELETE"

DELETE https://api.basistheory.com/atomic/cards/{id}

Delete an atomic card by ID in the tenant.

Permissions

card:delete token:write

URI Parameters

Parameter Required Type Default Description
id true string null The ID of the atomic card

Response Messages

Code Description
204 Atomic card successfully deleted
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 The atomic card was not found

Test Cards

To enable testing of atomic cards, we've implemented a list of acceptable test card numbers to ensure you are able to test with non-sensitive data.

Test card numbers

Card Description
4242424242424242 Test card
4000056655665556 Test card
5555555555554444 Test card
2223003122003222 Test card
5200828282828210 Test card
5105105105105100 Test card
378282246310005 Test card
371449635398431 Test card
6011111111111117 Test card
6011000990139424 Test card
3056930009020004 Test card
36227206271667 Test card
3566002020360505 Test card
620000000000000 Test card

Atomic Banks

Create Atomic Bank

Create Atomic Bank Request Example:

curl "https://api.basistheory.com/atomic/banks" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "POST"
  -D '{
      "bank": {
        "routing_number": "021000021",
        "account_number": "1234567890"
      }
    }
  }'

Create Atomic Bank Response Example:

{
  "id": "1485efb9-6b1f-4248-a5d1-cf9b3907164c",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "bank",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "bank": {
    "routing_number": "021000021",
    "account_number": "XXXXXX7890"
  }
}

POST https://api.basistheory.com/atomic/banks

Create a new atomic bank for the tenant.

Permissions

bank:create token:write

Request Schema

Attribute Required Type Default Description
bank true bank null Bank object

Bank Object Schema

Attribute Required Type Default Description
routing_number true string null Nine-digit ABA routing number
account_number true string null Account number up to seventeen-digits

Response Schema

Attribute Type Description
id string Unique identifier of the token which can be used to get an atomic bank
tenant_id string The tenant ID which owns the bank
type string Bank token type
created_by string The application ID which created the atomic bank
created_at string Created date of the application in ISO 8601 format
bank bank Masked bank object

Response Messages

Code Description
201 Atomic bank successfully created
400 Invalid request body. See Errors response for details
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions

List Atomic Banks

List Atomic Banks Request Example:

curl "https://api.basistheory.com/atomic/banks" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Atomic Banks Response Example:

{
  "pagination": {...}
  "data": [
    {
      "id": "1485efb9-6b1f-4248-a5d1-cf9b3907164c",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "type": "bank",
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2020-09-15T15:53:00+00:00",
      "bank": {
        "routing_number": "021000021",
        "account_number": "XXXXXX7890"
      }
    },
    {...},
    {...}
  ]
}

GET https://api.basistheory.com/atomic/banks

Get a list of atomic banks for the tenant.

Permissions

bank:read token:read

Response Schema

Returns the Pagination schema. The data attribute in the response contains an array of tokens with the following schema:

Attribute Type Description
id string Unique identifier of the token which can be used to get an atomic bank
tenant_id string The tenant ID which owns the bank
type string Bank token type
created_by string The application ID which created the atomic bank
created_at string Created date of the application in ISO 8601 format
bank bank Masked bank object

Response Messages

Code Description
200 Atomic banks successfully retrieved
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions

Get an Atomic Bank

Get Atomic Bank Request Example:

curl "https://api.basistheory.com/atomic/banks/1485efb9-6b1f-4248-a5d1-cf9b3907164c" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Atomic Bank Response Example:

{
  "id": "1485efb9-6b1f-4248-a5d1-cf9b3907164c",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "bank",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "bank": {
    "routing_number": "021000021",
    "account_number": "XXXXXX7890"
  }
}

GET https://api.basistheory.com/atomic/banks/{id}

Get an atomic bank by ID in the tenant.

Permissions

bank:read token:read

URI Parameters

Parameter Required Type Default Description
id true string null The ID of the atomic bank

Response Schema

Attribute Type Description
id string Unique identifier of the token which can be used to get an atomic bank
tenant_id string The tenant ID which owns the bank
type string Bank token type
created_by string The application ID which created the atomic bank
created_at string Created date of the application in ISO 8601 format
bank bank Masked bank object

Response Messages

Code Description
200 Atomic bank successfully retrieved
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 The atomic bank was not found

Delete Atomic Bank

Delete Token Request Example:

curl "https://api.basistheory.com/atomic/banks/1485efb9-6b1f-4248-a5d1-cf9b3907164c" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "DELETE"

DELETE https://api.basistheory.com/atomic/banks/{id}

Delete an atomic bank by ID in the tenant.

Permissions

bank:delete token:write

URI Parameters

Parameter Required Type Default Description
id true string null The ID of the atomic bank

Response Messages

Code Description
204 Atomic bank successfully deleted
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 The atomic bank was not found

Decrypt Atomic Bank

Decrypt Token Request Example:

curl "https://api.basistheory.com/atomic/banks/1485efb9-6b1f-4248-a5d1-cf9b3907164c/decrypt" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Decrypt Atomic Bank Response Example:

{
  "id": "1485efb9-6b1f-4248-a5d1-cf9b3907164c",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "bank",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "bank": {
    "routing_number": "021000021",
    "account_number": "1234567890"
  }
}

GET https://api.basistheory.com/atomic/banks/{id}/decrypt

Decrypt an atomic bank by ID in the tenant.

Permissions

bank:decrypt token:read

URI Parameters

Parameter Required Type Default Description
id true string null The ID of the atomic bank

Response Schema

Attribute Type Description
id string Unique identifier of the token which can be used to get an atomic bank
tenant_id string The tenant ID which owns the bank
type string Bank token type
created_by string The application ID which created the atomic bank
created_at string Created date of the application in ISO 8601 format
bank bank Masked bank object

Response Messages

Code Description
200 Atomic bank successfully decrypted
401 A missing or invalid X-API-KEY was provided
403 The provided X-API-KEY does not have the required permissions
404 The atomic bank was not found

Basis Theory JS

BasisTheory.js module allows consumers to tokenize any data they want within the browser of their customers, or at their backend systems. This will give you the power to continue to own the UX of your application, while still being able to off-load most of the risk and compliance of holding that data.

Install

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

# OR

yarn add @Basis-Theory/basis-theory-js
<script src="https://js.basistheory.com"></script>
// checkout shell and html language tabs
// checkout shell and html language tabs

BasisTheory.js is available for including in your site directly from https://js.basistheory.com or installing it as a module, and bundling/hosting it yourself within your site, or using it in your backend systems.

Initialize

// checkout other language tabs
<!-- This adds a window/global BasisTheory variable -->
<script src="https://js.basistheory.com"></script>

<!-- Somewhere in your site code -->
<script>
    // Here is an example on where to init BasisTheory, making sure the page has fully loaded.
    window.addEventListener('load', async () => {
      await BasisTheory.init("test_1234567890");
      // use BasisTheory
    });  
</script>
const BasisTheory = require('@Basis-Theory/basis-theory-js');

BasisTheory.init("test_1234567890").then(() => {
  // use BasisTheory
})
import BasisTheory from '@Basis-Theory/basis-theory-js';

await BasisTheory.init("test_1234567890");
// use BasisTheory

BasisTheory instance should be initialized only once, and it can be done whenever it suits best your workflow.

You will need a public Application API key to initialize the BasisTheory instance, this will give you access to both tokens and atomic features within the module.

The init method returns a short-lived Promise that resolves to the same BasisTheory instance. You may choose to ignore the yielded result, but it is strongly recommended to await for the Promise to resolve before performing any subsequent actions with BasisTheory instance.

Parameter Required Type Description
apiKey true string your public application's api key
options false object Options

BasisTheory Options

Parameter Required Type Default Description
elements false boolean false whether to load Hosted Elements

Make sure to replace test_1234567890 with your API key.

Tokenize

BasisTheory.tokens

General tokenization methods can be found under tokens service inside BasisTheory instance.

createToken

# checkout other language tabs
<script src="https://js.basistheory.com"></script>

<script>
  function tokenize() {
    const data = document.getElementById('data-input').value;
    BasisTheory.tokens.createToken(data).then((res) => {
      console.log(res.id)
    })
  }
</script>

<input id="data-input" type="text">
<button onclick="tokenize()">Tokenize</button>
const BasisTheory = require('@Basis-Theory/basis-theory-js');

// sample data
const data = {
  encryptedField: '1vauq19af...',
  myFlag: true,
  values: [1, 2, 3, 4],
}

BasisTheory.tokens.createToken(data)
  .then(function (res) {
    console.log(res.id); //token to store in your system
  });
import BasisTheory from '@Basis-Theory/basis-theory-js';

// sample data
const data = {
  encryptedField: '1vauq19af...',
  myFlag: true,
  values: [1, 2, 3, 4],
}

const { id } = await BasisTheory.tokens.createToken(data)
console.log(id); //token to store in your system

Make sure you've initialized BasisTheory

With createToken method, you can choose to tokenize plain or encrypted data, in any serializable format:

Parameter Required Type Description
data true string, number, boolean, object or array The data to tokenize

It returns a Promise that resolves to a TokenCreateResponse object:

Attribute Type Description
id string Unique identifier of the token
tenantId string The tenant ID which owns the token
type string Token type
createdAt string Created date of the token in ISO 8601 format

Internally, BasisTheory.tokens calls Create Token API and maps the response to conventionally named attributes.

getToken

# checkout javascript--node and typescript language tabs
<!-- We don't recommend fetching tokens at client-side -->
<!-- Checkout javascript--node and typescript language tabs. -->
const BasisTheory = require('@Basis-Theory/basis-theory-js');

const id = '25e2cd6b-2373-4cce-b9a0-98a9c65f53fb'; // previously stored token id

BasisTheory.tokens.getToken(id)
  .then(function (token) {
    console.log(token.data);
  });
import BasisTheory from '@Basis-Theory/basis-theory-js';

const id = '25e2cd6b-2373-4cce-b9a0-98a9c65f53fb'; // previously stored token id

const { data } = await BasisTheory.tokens.getToken(id);
console.log(data);

Make sure you've initialized BasisTheory

With getToken method, you can fetch tokenized data by a token id:

Parameter Required Type Description
id true string The id of the token

It returns a Promise that resolves to a GetTokenResponse object:

Attribute Type Description
id string Unique identifier of the token
ownerId string The tenant ID which owns the token
type string Token type
data any The data provided when creating the token
createdAt string Created date of the token in ISO 8601 format

Internally, BasisTheory.tokens calls Get Token API and maps the response to conventionally named attributes.

deleteToken

# checkout javascript--node and typescript language tabs
<!-- We don't recommend deleting tokens at client-side -->
<!-- Checkout javascript--node and typescript language tabs. -->
const BasisTheory = require('@Basis-Theory/basis-theory-js');

const id = '25e2cd6b-2373-4cce-b9a0-98a9c65f53fb'; // previously stored token id

BasisTheory.tokens.delete(id)
  .then(function () {
    // token has been deleted
   });
import BasisTheory from '@Basis-Theory/basis-theory-js';

const id = '25e2cd6b-2373-4cce-b9a0-98a9c65f53fb'; // previously stored token id

await BasisTheory.tokens.deleteToken(id);
// token has been deleted

Make sure you've initialized BasisTheory

With deleteToken method, you can delete tokenized data using a token id:

Parameter Required Type Description
id true string The id of the token

It returns a Promise of void.

Internally, BasisTheory.tokens calls Delete Token API.

Atomic

BasisTheory.atomic

storeCreditCard

# checkout other language tabs
<script src="https://js.basistheory.com"></script>

<script>
  function storeCreditCard() {
    const data = {
      card: {
        number: '4242424242424242',
        expirationMonth: 10,
        expirationYear: 25,
        cvc: '000',
      },
      billingDetails: {
        name: 'Fiona Theory',
      },
    };
    BasisTheory.atomic.storeCreditCard(data).then((res) => {
      console.log(res.id)
    })
  }
</script>
const BasisTheory = require('@Basis-Theory/basis-theory-js');

const data = {
  card: {
    number: '4242424242424242',
    expirationMonth: 10,
    expirationYear: 25,
    cvc: '000',
  },
  billingDetails: {
    name: 'Fiona Theory',
  },
};

BasisTheory.atomic.storeCreditCard(data).then((res) => {
  console.log(res.id)
})
import BasisTheory from '@Basis-Theory/basis-theory-js';

const data = {
  card: {
    number: '4242424242424242',
    expirationMonth: 10,
    expirationYear: 25,
    cvc: '000',
  },
  billingDetails: {
    name: 'Fiona Theory',
  },
};

const { id } = await BasisTheory.atomic.storeCreditCard(data);
console.log(res.id);

Make sure you've initialized BasisTheory

With storeCreditCard method, you can tokenize any credit card to securely store and integrate with you atomic cards, in any way you need.

In most scenarios, this reliefs the burden of full PCI compliance.

Attribute Required Type Description
card true object CardModel object
billingDetails false object BillingDetailsModel object

CardModel

Attribute Required Type Description
number true string The card number without any separators
expirationMonth true integer Two-digit number representing the card's expiration month
expirationYear true integer Four-digit number representing the card's expiration year

BillingDetailsModel

Attribute Required Type Description
name false string The cardholder or customer's full name
email false string The cardholder or customer's email address
phone false string The cardholder or customer's phone number
address false object The cardholder or customer's address

AddressModel

Attribute Required Type Description
line1 false string Address line 1 (Street address / PO Box / Company name)
line2 false string Address line 2 (Apartment / Suite / Unit / Building)
city false string City / District / Suburb / Town / Village
state false string State / County / Province / Region
postal_code false string Zip or postal code
country false string Two-character ISO country code (e.g. US)

Examples

We have 2 fully functional examples for how to use our javascript modules to store any data you want into your token infrastructure.

Store PII example

We have a vanilla javascript example that will enable you to create PII in a browser, tokenize it and get a token back to be stored within your system.

Check it out here

Store credit card example

If you have the correct PCI compliant systems and certifications, you'll be able to create atomic cards from within your code using our vanilla javascript example. Follow it here:

Check it out here

Hosted Elements

  BasisTheory.elements

BasisTheory Hosted Elements are simple, secure, developer-friendly inputs that empowers 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:

Install / Initialize

// checkout other language tabs
<script src="https://js.basistheory.com"></script>

<!-- Somewhere in your site code -->
<script>
    window.addEventListener('load', async () => {
      await BasisTheory.init("test_1234567890", { elements: true });
      // use BasisTheory.elements
    });  
</script>
const BasisTheory = require('@Basis-Theory/basis-theory-js');

BasisTheory.init("test_1234567890", { elements: true }).then(() => {
  // use BasisTheory.elements
})
import BasisTheory from '@Basis-Theory/basis-theory-js';

await BasisTheory.init("test_1234567890", { elements: true });
// use BasisTheory.elements

Make sure to replace test_1234567890 with your API key.

You don't have to install Hosted Elements as a separated module or include additional script tags besides BasisTheory.js. It will dynamically load them from js.basistheory.com, which enables us to keep the highest compliance standards (e.g. PCI compliance). The only thing you have to worry about is adding elements: true in BasisTheory.init options parameter.

See Basis Theory Initialize for more details.

Elements instance

Create Element

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

This method returns an instance of an element type.

Parameter Required Type Description
type true 'card' Type of the element you want to create

Element instance

Mount Element

// checkout html language tab
<div id="my-card"></div>

<script>
  cardElement.mount('#my-card')
</script>
// checkout html language tab
// checkout html language tab

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

Unmount Element

cardElement.unmount();

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

Element Events

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

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

Make sure to replace 'event-type' with an actual 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

element.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

element.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) relevantly 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,
  "errors": [
    "invalid-field"
  ]
}
Attribute Type Description
complete 'change' If the element value is well-formed and is ready to be submitted.
errors array Array of element validation error types

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 element validation error types, in case of client-side error.
response 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)