Services

Basis Theory Web Elements offers several methods and to interact with the underlying data and services to collect or share data safely.

Methods

Once you have created and mounted an element instance, you can invoke the methods below:

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

<script>
  var cardElement = bt.createElement("card");
  await cardElement.mount("#my-card");

  cardElement.focus();
</script>

Name	Resulting Type	Eligible Elements	Description
`clear`	void	All	Clears the element input(s) value.
`focus`	void	All	Focuses on the element input.
`blur`	void	All	Blurs the element input.
`month`	number	cardExpirationDate	Data-parsing method that resolves to the month value of the input date, where "January" = 1.
`year`	number	cardExpirationDate	Data-parsing method that resolves to the four-digit year value of the input date.
`format`*	string	cardExpirationDate	Data-parsing method that takes a date format as an argument and returns the expiration date in the given format.
`setValue`	void	All	Accepts a synthetic reference from a retrieved token and safely sets it as the input value.
`setValueRef`*	void	`text` `cardNumber` `cardExpirationDate` `cardElement` `cardVerificationCode`	Sets the element's value to the value of the provided element.

Format*

Our card expiration date format implements Luxon's toFormat, so all of Luxon's date formatting tokens are available.

Card Expiration Date format example
const cardExpirationDateElement = bt.createElement("cardExpirationDate", {
  targetId: "expirationDate",
  value: "04/25",
});

...

const requestBody = {
  ...
  expiration_date1: cardExpirationDateElement.format("yyyy-MM"), // 2025-04
  expiration_date2: cardExpirationDateElement.format("MM"),      // 04
  expiration_date3: cardExpirationDateElement.format("M"),       // 4
  expiration_date4: cardExpirationDateElement.format("MM/yyyy"), // 04/2025
  expiration_date5: cardExpirationDateElement.format("yy"),      // 25
  ...
}

setValueRef*

Sets the element's value to the value of the provided element.

Card Expiration Date setValueRef example
const cardExpirationDateElement = bt.createElement("cardExpirationDate", {
  targetId: "expirationDate",
  value: "04/25",
});

const cardExpirationDateElementReadOnly = bt.createElement("cardExpirationDate", {
  targetId: "expirationDateReadOnly",
  readOnly: true
});

cardExpirationDateElementReadOnly.setValueRef(cardExpirationDateElement)

cardExpirationDateElementReadOnly will be updated every time the value of cardExpirationDateElement changes.

When using setValueRef to keep an element in sync with another element, or to set the text of an element, it is strongly recommended that you make the element that is being acted upon readonly. This is possible by setting readOnly to true.

Tokenization Services

Element values can be securely tokenized by simply passing the Element instance (or one of its data parsing methods) in the tokenization payload.

The actual input data never leaves the element (iframe) other than to hit our secure API endpoints.

When submitting plainText values, data will be HTML encoded before storage for security reasons.

Create Token

The examples below show how to use Elements instances in the payload of the tokens.create service.

Create generic token
bt.tokens
  .create({
    type: "token",
    data: {
      sensitiveData: sensitiveDataElement,
      nonSensitiveData: "plainText", // see warning on plain text data
      otherData: {
        someInteger: 20,
        someBoolean: false,
      },
      someOtherData: ["plainText1", "plainText2"],
    },
    metadata: {
      nonSensitiveField: "nonSensitiveValue",
    },
  })
  .then((token) => {
    console.log(token.id); // token to store
    console.log(JSON.stringify(token)); // full response
  });

Create card token from CardElement
bt.tokens
  .create({
    type: "card",
    data: cardElement,
  })
  .then((token) => {
    console.log(token.id); // token to store
    console.log(JSON.stringify(token.data)); // masked card data
  });

Create card token from multiple Elements
bt.tokens
  .create({
    type: "card",
    data: {
      number: cardNumberElement,
      expiration_month: cardExpirationDateElement.month(),
      expiration_year: cardExpirationDateElement.year(),
      cvc: cardVerificationCodeElement
    }
  })
  .then((token) => {
    console.log(token.id); // token to store
    console.log(JSON.stringify(token.data)); // masked card data
  });

Create bank token
bt.tokens
  .create({
    type: "bank",
    data: {
      routingNumber: routingNumberElement,
      accountNumber: accountNumberElement,
    },
  })
  .then((token) => {
    console.log(token.id); // token to store
    console.log(JSON.stringify(token.data)); // redacted bank data
  });

Tokenize

The example below shows how to use Elements instances in the payload of the tokenize service.

Tokenize data
bt.tokenize({
  card1: {
    type: "card",
    data: cardElement,
  },
  card2: {
    type: "card",
    data: {
      number: cardNumberElement,
      expiration_month: cardExpirationDateElement.month(),
      expiration_year: cardExpirationDateElement.year(),
      cvc: cardVerificationCodeElement,
    },
  },
  sensitiveData: sensitiveDataElement,
  nonSensitiveData: "plainText", // see warning on plain text data
  otherData: {
    someInteger: 20,
    someBoolean: false,
  },
  someOtherData: ["plainText1", "plainText2"],
}).then((tokens) => {
  console.log(tokens.card1.id, tokens.card2.id, tokens.sensitiveData); // token to store
  console.log(JSON.stringify(tokens)); // full response
});

Token Update

Aside from creating tokens, an Element value can be used to update a token using tokens.update. To do that, simply pass the Element instance (or one of its data parsing methods) in the payload.

bt.tokens
  .update("ca9f3fd7-3906-4087-83aa-9a6129221297", {
    // replace w/ desired token id
    data: cardElement,
  })
  .then((token) => {
    console.log(JSON.stringify(token.data)); // redacted updated token data
  });

Create Token Intent

The examples below show how to use Elements instances in the payload of the tokenIntents.create service.

Create card token intent from a CardElement
bt.tokenIntents
  .create({
    type: "card",
    data: cardElement
  })
  .then((tokenIntent) => {
    console.log(tokenIntent.id); // token intent id to validate and convert to a token
  });

Create card token intent from multiple Elements
bt.tokenIntents
  .create({
    type: "card",
    data: {
      number: cardNumberElement,
      expiration_month: cardExpirationDateElement.month(),
      expiration_year: cardExpirationDateElement.year(),
      cvc: cardVerificationCodeElement
    }
  })
  .then((tokenIntent) => {
    console.log(tokenIntent.id); // token intent id to validate and convert to a token
  });

Sessions

The Session service in the Basis Theory Web Elements SDK provides a secure way to access and interact with sensitive data in frontend applications. Key capabilities include:

Secure Token Retrieval: Retrieve and display tokenized data, such as masked payment details or partial SSNs, without exposing raw values.
Temporary Elevated Access: Grant limited-time permissions for actions like updating stored payment methods or verifying identity.

By leveraging Sessions, the Web Elements SDK enhances security while enabling seamless frontend experiences. Learn more.

Create Session

Create a new session for a Public Application.

Create a session
  const session = await bt.sessions.create()

Authorize a session

Sessions cannot be authorized directly from the frontend. All session authorization must be performed by a Private Application on the backend. This security measure ensures that sensitive operations are executed in a controlled environment, reducing exposure to potential threats.

Detokenization Services

Element values can be securely detokenized and revealed using these detokenization services and the Element's setValue method.

Retrieve Token

When retrieve is called from a Basis Theory instance, the API request is made from inside a Basis Theory hosted iframe and the returned data remains within it. The examples below show how to use retrieve and setValue, but for more information on revealing and session keys, visit the Reveal Tokenized Data guide.

Retrieve 'string' token data and set value into TextElement
const textElement = bt.createElement("text", {
  targetId: "text-element",
});

bt.tokens
  .retrieve("ca9f3fd7-3906-4087-83aa-9a6129221297", {
    apiKey: "<SESSION_API_KEY>", // api key is required and should belong to a session
  })
  .then((token) => {
    textElement.setValue(token.data);
  });

Retrieve card token and set value into CardElement
const cardElement = bt.createElement("card");

bt.tokens
  .retrieve("ca9f3fd7-3906-4087-83aa-9a6129221297", {
    apiKey: "<SESSION_API_KEY>", // api key is required and should belong to a session
  })
  .then((token) => {
    cardElement.setValue(token.data);
  });

// or

bt.tokens
  .retrieve("ca9f3fd7-3906-4087-83aa-9a6129221297", {
    apiKey: "<SESSION_API_KEY>", // api key is required and should belong to a session
  })
  .then((token) => {
    cardElement.setValue({
      number: token.data.number, // expects string
      expiration_month: token.data.expiration_month, // expects number
      expiration_year: token.data.expiration_year, // expects number
    });
  });

Retrieve card token and set value into split card elements
const cardNumberElement = bt.createElement("cardNumber", {
  targetId: "card-number",
});
const cardExpirationDateElement = bt.createElement("cardExpirationDate", { targetId: "card-expiration-date" });

bt.tokens
  .retrieve("ca9f3fd7-3906-4087-83aa-9a6129221297", {
    apiKey: "<SESSION_API_KEY>", // api key is required and should belong to a session
  })
  .then((token) => {
    cardNumberElement.setValue(token.data.number);
    cardExpirationDateElement.setValue({
      month: token.data.expiration_month,
      year: token.data.expiration_year,
    });
  });

The data attribute in the token returned by the retrieve method is not the actual data, but a a synthetic representation of the sensitive detokenized data.

Token attributes such as metadata are directly accessible from the retrieve response as they are considered non-sensitive.

Proxy Service

This service wraps the proxy API endpoint to proxy a request to a third-party API.

Invoking Proxy

When a proxy is invoked from a Basis Theory instance, the API request is made from inside a Basis Theory hosted iframe and the returned data remains within it, whether the proxy has Elements instances in its body or not. The examples below show how to invoke the proxy and use setValue, but for more information on revealing and session keys, visit the Reveal Data from 3rd Party guide. Elements can be used to proxy data securely by including them in the proxy body as shown in the example.

Invoking Pre-Configured Proxy w/ POST
const submitElement = bt.createElement("text", {
  targetId: "submitElement",
});
const revealElement = bt.createElement("text", {
  targetId: "revealElement",
});

bt.proxy
  .post({
    headers: {
      "BT-PROXY-KEY": "e29a50980ca5", // replace with your pre-configured proxy key (if pre-configured)
    },
    body: {
      sensitiveValue: submitElement,
      nonSensitiveValue: "plainText",
    },
    apiKey: "<SESSION_API_KEY>",
  })
  .then((response) => {
    revealElement.setValue(response.value);
  });

The proxy response object returned after invoking it with elements is not the actual data, but a a synthetic representation of the sensitive data.

Proxy Invocation Methods

The Elements proxy service supports all of the same HTTP methods that the ephemeral or pre-configured proxy APIs support. All proxy calls take the same options object as a parameter.

Signature	Description
`get(proxyRequest: ProxyRequestOptions)`	Performs a proxy GET request.
`post(proxyRequest: ProxyRequestOptions)`	Performs a proxy POST request.
`put(proxyRequest: ProxyRequestOptions)`	Performs a proxy PUT request.
`patch(proxyRequest: ProxyRequestOptions)`	Performs a proxy PATCH request.
`delete(proxyRequest: ProxyRequestOptions)`	Performs a proxy DELETE request.

ProxyRequestOptions

Attribute	Type	Required	Description
`path`	string	false	String that gets added to the end of the proxied URL path.
`query`	object	false	Key/Value pairs that are added as a query parameter to the proxied URL.
`headers`	object	false	Key/Value pairs that are added as headers when invoking the proxied URL.
`body`	object	false	Payload that gets sent to the proxied URL. Can contain Elements.
`apiKey`	object	false	BasisTheory API Key for authentication
`correlationId`	object	false	ID that can be used for request correlation
`idempotencyKey`	object	false	Key used for request idempotency

Access non-sensitive responses from Proxy calls
Beta

Our Elements enable you to convert proxy responses into plain text, which is ideal for non-sensitive data handling. This enhancement streamlines your data processing workflows and facilitates an easier understanding of the returned data, bypassing decryption or tokenization.

This feature is currently invite-only. If you're interested, please get in touch for an invitation.

You can capture values from any of our Elements; hence we strongly recommend only using this feature for non-sensitive data. Converting proxy responses to plain text can expose the underlying data to risks, such as unauthorized access or leakage. Ensure the plain-text proxy responses align with your data security policy, data handling practices, and compliance obligations. If you're unsure, please get in touch for guidance at www.basistheory.com/contact

HTTP Client Service

Element values can be used in a request to a third-party API using our HTTP client service.

Post

The example below shows how to use the HTTP client service to make a POST request to a third-party API with an element in the payload.

Invoking HTTP Client Service w/ POST
const bt = await basistheory("<API_KEY>");

bt.client.post(
  "https://www.api.thirdpartydomain.com/resources",
  {
    sensitiveData: sensitiveDataElement,
    nonSensitiveData: "plainText", // see warning on plain text data
    otherData: {
      someInteger: 20,
      someBoolean: false,
    },
    someOtherData: ["plainText1", "plainText2"],
  },
  {
    headers: {
      "Content-Type": "application/json",
    },
  }
).then((response) => {
  console.log(JSON.stringify(response)); // full plaintext response
});

The response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

Put

The example below shows how to use the HTTP client service to make a PUT request to a third-party API with an element in the payload.

Invoking HTTP Client Service w/ PUT
const bt = await basistheory("<API_KEY>");

bt.client.put(
  "https://www.api.thirdpartydomain.com/resources/id",
  {
    sensitiveData: sensitiveDataElement,
    nonSensitiveData: "plainText", // see warning on plain text data
    otherData: {
      someInteger: 20,
      someBoolean: false,
    },
    someOtherData: ["plainText1", "plainText2"],
  },
  {
    headers: {
      "Content-Type": "application/json",
      Accept: "application/json",
    },
  }
).then((response) => {
  console.log(JSON.stringify(response)); // full plaintext response
});

The response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

Patch

The example below shows how to use the HTTP client service to make a PATCH request to a third-party API with an element in the payload.

Invoking HTTP Client Service w/ PATCH
const bt = await basistheory("<API_KEY>");

bt.client.patch(
  "https://www.api.thirdpartydomain.com/resources/id",
  {
    sensitiveData: sensitiveDataElement,
    nonSensitiveData: "plainText", // see warning on plain text data
    otherData: {
      someInteger: 20,
      someBoolean: false,
    },
    someOtherData: ["plainText1", "plainText2"],
  },
  {
    headers: {
      "Content-Type": "application/json",
      Accept: "application/json",
    },
  }
).then((response) => {
  console.log(JSON.stringify(response)); // full plaintext response
});

The response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

Get

The example below shows how to use the HTTP client service to make a GET request to a third-party API.

Invoking HTTP Client Service w/ GET
const bt = await basistheory("<API_KEY>");

bt.client.get("https://www.api.thirdpartydomain.com/resources/id", {
  headers: {
    Accept: "application/json",
  },
}).then((response) => {
  console.log(JSON.stringify(response)); // full plaintext response
});

The response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

Delete

The example below shows how to use the HTTP client service to make a DELETE request to a third-party API.

Invoking HTTP Client Service w/ DELETE
const bt = await basistheory("<API_KEY>");

bt.client.delete("https://www.api.thirdpartydomain.com/resources/id", {
  headers: {
    Accept: "application/json",
  },
}).then((response) => {
  console.log(JSON.stringify(response)); // full plaintext response
});

The response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

Errors

Basis Theory Service Errors

Basis Theory element services could throw an error based on client-side validations or if the server rejects the request.

Handling services errors
import { BasisTheoryApiError, BasisTheoryValidationError } from "@basis-theory/web-elements/common";

bt.tokenize({
  card1: {
    type: "card",
    data: cardElement1,
  },
  card2: {
    type: "card",
    data: cardElement2,
  },
  ssn: textElement,
}).catch((error) => {
  if (error instanceof BasisTheoryValidationError) {
    // only applies to tokenization
    // check error details
  } else if (error instanceof BasisTheoryApiError) {
    // check error data or status
  }
});

HTTP Client Service Errors

HTTP client services could throw an error based on client-side validations or if the server rejects the request.

Handling services errors
import { HttpClientError, BasisTheoryValidationError } from "@basis-theory/web-elements/common";

const bt = await basistheory("<API_KEY>");

bt.client.post({
  sensitiveData: textElement,
}).catch((error) => {
  if (error instanceof BasisTheoryValidationError) {
    // check error details
  } else if (error instanceof HttpClientError) {
    // check error data, status, or headers
  }
});

BasisTheoryValidationError

{
  details: {
    card1: {
      number: {
        type: 'invalid'
      },
      cvc: {
        type: 'incomplete'
      }
    },
    card2: {
    }
  },
  validation: [] // deprecated
}

Attribute	Type	Description
`name`	string	Error name, always `'BasisTheoryValidationError'`.
`details`	object	Maps payload properties to their respective element's validation problems.

BasisTheoryApiError

{
  data: {
    // API response body
  },
  status: 400
}

Attribute	Type	Description
`name`	string	Error name, always `'BasisTheoryApiError'`.
`data`	object	Response body sent from the server.
`status`	number	Response HTTP status.

Error name property may be used instead of checking its instance type.

HttpClientError

{
  data: {...},
  status: 400,
  headers: {...}
}

Attribute	Type	Description
`name`	string	Error name, always `'HttpClientError'`.
`data`	object	Response body sent from the server.
`status`	number	Response HTTP status.
`headers`	object	Response HTTP headers.

The response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

Methods​

Format*​

setValueRef*​

Tokenization Services​

Create Token​

Tokenize​

Token Update​

Create Token Intent​

Sessions​

Create Session​

Authorize a session​

Detokenization Services​

Retrieve Token​

Proxy Service​

Invoking Proxy​

Proxy Invocation Methods​

ProxyRequestOptions​

Access non-sensitive responses from Proxy calls Beta​

HTTP Client Service​

Post​

Put​

Patch​

Get​

Delete​

Errors​

Basis Theory Service Errors​

HTTP Client Service Errors​

BasisTheoryValidationError​

BasisTheoryApiError​

HttpClientError​

Methods

Format*

setValueRef*

Tokenization Services

Create Token

Tokenize

Token Update

Create Token Intent

Sessions

Create Session

Authorize a session

Detokenization Services

Retrieve Token

Proxy Service

Invoking Proxy

Proxy Invocation Methods

ProxyRequestOptions

Access non-sensitive responses from Proxy calls
Beta

HTTP Client Service

Post

Put

Patch

Get

Delete

Errors

Basis Theory Service Errors

HTTP Client Service Errors

BasisTheoryValidationError

BasisTheoryApiError

HttpClientError