Services

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

Methods

Once you have declared an Element component, you can use its ref to invoke the methods below:

import { useRef } from "react";
import { useBasisTheory, BasisTheoryProvider, TextElement } from "@basis-theory/basis-theory-react";

const MyForm = () => {
  const { bt } = useBasisTheory("<API_KEY>", { elements: true }); // replace <API_KEY> w/ your public API key
  const fullNameRef = useRef(null);

  fullNameRef.focus(); // calling focus method

  return (
    <BasisTheoryProvider bt={bt}>
      <TextElement id="fullName" ref={fullNameRef} placeholder="Full name" aria-label="Full name" />
    </BasisTheoryProvider>
  );
};

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.
`setValue`	void	All	Accepts a synthetic reference from a retrieved token and safely sets it as the input value.

Tokenization Services

Elements' values can be securely tokenized by simply passing the Element ref 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
import { useRef } from "react";
import { useBasisTheory, BasisTheoryProvider, TextElement, BasisTheoryValidationError, BasisTheoryApiError } from "@basis-theory/basis-theory-react";

const MyForm = () => {
  const { bt } = useBasisTheory("<API_KEY>", { elements: true }); // replace <API_KEY> w/ your public API key
  const fullNameRef = useRef(null);

  const submit = async () => {
    const fullName = fullNameRef.current;

    try {
      const token = await bt.tokens.create({
        type: "token",
        data: {
          name: fullName,
          nonSensitiveData: "plainText",
        },
        metadata: {
          nonSensitiveField: "nonSensitiveValue",
        },
      });

      console.log(token.id); // token to share
      console.log(JSON.stringify(token)); // full response
    } catch (error) {
      if (error instanceof BasisTheoryValidationError) {
        // check error details
      } else if (error instanceof BasisTheoryApiError) {
        // check error data or status
      }
    }
  };

  return (
    <BasisTheoryProvider bt={bt}>
      <TextElement id="fullName" ref={fullNameRef} placeholder="Full name" aria-label="Full name" />
      <div>
        <button type="submit" onClick={submit} disabled={!bt}>
          Submit
        </button>
      </div>
    </BasisTheoryProvider>
  );
};

Create card token
import { useRef } from "react";
import { useBasisTheory, BasisTheoryProvider, CardElement, BasisTheoryValidationError, BasisTheoryApiError } from "@basis-theory/basis-theory-react";

const MyForm = () => {
  const { bt } = useBasisTheory("<API_KEY>", { elements: true }); // replace <API_KEY> w/ your public API key
  const cardRef = useRef(null);

  const submit = async () => {
    const card = cardRef.current;

    try {
      const token = await bt.tokens.create({
        type: "card",
        data: card,
        metadata: {
          nonSensitiveField: "nonSensitiveValue",
        },
      });

      console.log(token.id); // token to share
      console.log(JSON.stringify(token)); // full response
    } catch (error) {
      if (error instanceof BasisTheoryValidationError) {
        // check error details
      } else if (error instanceof BasisTheoryApiError) {
        // check error data or status
      }
    }
  };

  return (
    <BasisTheoryProvider bt={bt}>
      <CardElement id="card" ref={cardRef} />
      <div>
        <button type="submit" onClick={submit} disabled={!bt}>
          Submit
        </button>
      </div>
    </BasisTheoryProvider>
  );
};

Tokenize

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

Tokenize data
import { useRef } from "react";
import { useBasisTheory, BasisTheoryProvider, TextElement, CardElement, CardNumberElement, CardExpirationDateElement, CardVerificationCodeElement, BasisTheoryValidationError, BasisTheoryApiError } from "@basis-theory/basis-theory-react";

const MyForm = () => {
  const { bt } = useBasisTheory("<API_KEY>", { elements: true }); // replace <API_KEY> w/ your public API key
  const cardRef = useRef(null);
  const cardNumberRef = useRef(null);
  const cardExpirationDateRef = useRef(null);
  const cardVerificationCodeRef = useRef(null);
  const fullNameRef = useRef(null);

  const submit = async () => {
    const card = cardRef.current;
    const cardNumber = cardNumberRef.current;
    const cardExpirationDate = cardExpirationDateRef.current;
    const cardVerificationCode = cardVerificationCodeRef.current;
    const fullName = fullNameRef.current;

    try {
      const tokens = await bt.tokenize({
        card1: {
          type: "card",
          data: card,
        },
        card2: {
          type: "card",
          data: {
            number: cardNumber,
            expiration_month: cardExpirationDate.month(),
            expiration_year: cardExpirationDate.year(),
            cvc: cardVerificationCode,
          },
        },
        name: fullName,
        nonSensitiveData: "plainText", // see warning on plain text data
        otherData: {
          someInteger: 20,
          someBoolean: false,
        },
        someOtherData: ["plainText1", "plainText2"],
      });

      console.log(tokens.card1.id, tokens.card2.id, tokens.name); // token to store
      console.log(JSON.stringify(tokens)); // full response
    } catch (error) {
      if (error instanceof BasisTheoryValidationError) {
        // check error details
      } else if (error instanceof BasisTheoryApiError) {
        // check error data or status
      }
    }
  };

  return (
    <BasisTheoryProvider bt={bt}>
      <CardElement id="card" ref={cardRef} />
      <CardNumberElement id="cardNumber" ref={cardNumberRef} />
      <CardExpirationDateElement id="cardExpirationDate" ref={cardExpirationDateRef} />
      <CardVerificationCodeElement id="cardVerificationCode" ref={cardVerificationCodeRef} />
      <TextElement id="fullName" ref={fullNameRef} placeholder="Full name" aria-label="Full name" />
      <div>
        <button type="submit" onClick={submit} disabled={!bt}>
          Submit
        </button>
      </div>
    </BasisTheoryProvider>
  );
};

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.

import { useRef } from "react";
import { useBasisTheory, BasisTheoryProvider, TextElement, BasisTheoryValidationError, BasisTheoryApiError } from "@basis-theory/basis-theory-react";

const MyForm = () => {
  const { bt } = useBasisTheory("<API_KEY>", { elements: true }); // replace <API_KEY> w/ your public API key
  const fullNameRef = useRef(null);

  const submit = async () => {
    const fullName = fullNameRef.current;

    try {
      const token = await bt.tokens.update("ca9f3fd7-3906-4087-83aa-9a6129221297", {
        // replace w/ desired token id
        data: {
          name: fullName,
        },
      });

      console.log(JSON.stringify(token.data)); // redacted updated token data
    } catch (error) {
      if (error instanceof BasisTheoryValidationError) {
        // check error details
      } else if (error instanceof BasisTheoryApiError) {
        // check error data or status
      }
    }
  };

  return (
    <BasisTheoryProvider bt={bt}>
      <TextElement id="fullName" ref={fullNameRef} placeholder="Full name" aria-label="Full name" />
      <div>
        <button type="submit" onClick={submit} disabled={!bt}>
          Submit
        </button>
      </div>
    </BasisTheoryProvider>
  );
};

Detokenization Services

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

Retrieve Token

When retrieve is called from a Basis Theory instance configured with elements: true, 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
import { useRef } from "react";
import { useBasisTheory, BasisTheoryProvider, TextElement } from "@basis-theory/basis-theory-react";

const MyForm = () => {
  const { bt } = useBasisTheory("<API_KEY>", { elements: true }); // replace <API_KEY> w/ your public API key
  const textRef = useRef(null);

  const reveal = async () => {
    const textElement = textRef.current;

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

      textElement.setValue(token.data);
    } catch (error) {
      // handle error
    }
  };

  return (
    <BasisTheoryProvider bt={bt}>
      <TextElement id="textElement" ref={textRef} />
      <div>
        <button type="submit" onClick={reveal} disabled={!bt}>
          Reveal
        </button>
      </div>
    </BasisTheoryProvider>
  );
};

Retrieve card token and set value into CardElement
import { useRef } from "react";
import { useBasisTheory, BasisTheoryProvider, CardElement } from "@basis-theory/basis-theory-react";

const MyForm = () => {
  const { bt } = useBasisTheory("<API_KEY>", { elements: true }); // replace <API_KEY> w/ your public API key
  const cardRef = useRef(null);

  const reveal = async () => {
    const cardElement = cardRef.current;

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

      // card object
      cardElement.setValue(token.data);

      // or

      // split approach
      cardElement.setValue({
        number: token.data.number, // expects string
        expiration_month: token.data.expiration_month, // expects number
        expiration_year: token.data.expiration_year, // expects number
      });
    } catch (error) {
      // handle error
    }
  };

  return (
    <BasisTheoryProvider bt={bt}>
      <CardElement id="cardElement" ref={cardRef} />
      <div>
        <button type="submit" onClick={reveal} disabled={!bt}>
          Reveal
        </button>
      </div>
    </BasisTheoryProvider>
  );
};

Retrieve card token and set value into split card elements
import { useRef } from "react";
import { useBasisTheory, BasisTheoryProvider, CardNumberElement, CardExpirationDateElement } from "@basis-theory/basis-theory-react";

const MyForm = () => {
  const { bt } = useBasisTheory("<API_KEY>", { elements: true }); // replace <API_KEY> w/ your public API key
  const cardNumberRef = useRef(null);
  const cardExpirationDateRef = useRef(null);

  const reveal = async () => {
    const cardNumberElement = cardNumberRef.current;
    const cardExpirationDateElement = cardExpirationDateRef.current;

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

      cardNumberElement.setValue(token.data.number);
      cardExpirationDateElement.setValue({
        month: token.data.expiration_month,
        year: token.data.expiration_year,
      });
    } catch (error) {
      // handle error
    }
  };

  return (
    <BasisTheoryProvider bt={bt}>
      <CardNumberElement id="cardNumber" ref={cardNumberRef} />
      <CardExpirationDateElement id="cardExpirationDate" ref={cardExpirationDateRef} />
      <div>
        <button type="submit" onClick={reveal} disabled={!bt}>
          Reveal
        </button>
      </div>
    </BasisTheoryProvider>
  );
};

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 configured with elements: true, 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
import { useRef } from "react";
import { useBasisTheory, BasisTheoryProvider, TextElement } from "@basis-theory/basis-theory-react";

const MyForm = () => {
  const { bt } = useBasisTheory("<API_KEY>", { elements: true }); // replace <API_KEY> w/ your public API key
  const submitRef = useRef(null);
  const revealRef = useRef(null);

  const proxyAndReveal = async () => {
    const submitElement = submitRef.current;
    const revealElement = revealRef.current;

    try {
      const response = await 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>",
      });

      revealElement.setValue(response.value);
    } catch (error) {
      // handle error
    }
  };

  return (
    <BasisTheoryProvider bt={bt}>
      <TextElement id="submitElement" ref={submitRef} />
      <TextElement id="revealElement" ref={revealRef} />
      <div>
        <button type="submit" onClick={proxyAndReveal} disabled={!bt}>
          Proxy and Reveal
        </button>
      </div>
    </BasisTheoryProvider>
  );
};

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
import { useRef } from "react";
import { useBasisTheory, BasisTheoryProvider, CardNumberElement, CardExpirationDateElement, CardVerificationCodeElement, BasisTheoryValidationError, HttpClientError } from "@basis-theory/basis-theory-react";

const MyForm = () => {
  const { bt } = useBasisTheory("<API_KEY>", { elements: true }); // replace <API_KEY> w/ your public API key
  const cardNumberRef = useRef(null);
  const cardExpirationDateRef = useRef(null);
  const cardVerificationCodeRef = useRef(null);

  const submit = async () => {
    const cardNumber = cardNumberRef.current;
    const cardExpirationDate = cardExpirationDateRef.current;
    const cardVerificationCode = cardVerificationCodeRef.current;

    try {
      const response = await bt.client.post('https://www.api.thirdpartydomain.com/resources', {
        number: cardNumber,
        expiration_month: cardExpirationDate.month(),
        expiration_year: cardExpirationDate.year(),
        cvc: cardVerificationCode,
        nonSensitiveData: "plainText",
      }, {
        headers: {
          'Content-Type': 'application/json',
          'Accept': 'application/json',
        },
      });

      console.log(JSON.stringify(response)); // full plaintext response
    } catch (error) {
      if (error instanceof BasisTheoryValidationError) {
        // check error details
      } else if (error instanceof HttpClientError) {
        // check error data, status, or headers
      }
    }
  };

  return (
    <BasisTheoryProvider bt={bt}>
      <CardNumberElement id="cardNumber" ref={cardNumberRef} />
      <CardExpirationDateElement id="cardExpirationDate" ref={cardExpirationDateRef} />
      <CardVerificationCodeElement id="cardVerificationCode" ref={cardVerificationCodeRef} />
      <div>
        <button type="submit" onClick={submit} disabled={!bt}>
          Submit
        </button>
      </div>
    </BasisTheoryProvider>
  );
};

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
import { useRef } from "react";
import { useBasisTheory, BasisTheoryProvider, CardNumberElement, CardExpirationDateElement, CardVerificationCodeElement, BasisTheoryValidationError, HttpClientError } from "@basis-theory/basis-theory-react";

const MyForm = () => {
  const { bt } = useBasisTheory("<API_KEY>", { elements: true }); // replace <API_KEY> w/ your public API key
  const cardNumberRef = useRef(null);
  const cardExpirationDateRef = useRef(null);
  const cardVerificationCodeRef = useRef(null);

  const submit = async () => {
    const cardNumber = cardNumberRef.current;
    const cardExpirationDate = cardExpirationDateRef.current;
    const cardVerificationCode = cardVerificationCodeRef.current;

    try {
      const response = await bt.client.put('https://www.api.thirdpartydomain.com/resources/id', {
        number: cardNumber,
        expiration_month: cardExpirationDate.month(),
        expiration_year: cardExpirationDate.year(),
        cvc: cardVerificationCode,
        nonSensitiveData: "plainText",
      }, {
        headers: {
          'Content-Type': 'application/json',
          'Accept': 'application/json',
        },
      });

      console.log(JSON.stringify(response)); // full plaintext response
    } catch (error) {
      if (error instanceof BasisTheoryValidationError) {
        // check error details
      } else if (error instanceof HttpClientError) {
        // check error data, status, or headers
      }
    }
  };

  return (
    <BasisTheoryProvider bt={bt}>
      <CardNumberElement id="cardNumber" ref={cardNumberRef} />
      <CardExpirationDateElement id="cardExpirationDate" ref={cardExpirationDateRef} />
      <CardVerificationCodeElement id="cardVerificationCode" ref={cardVerificationCodeRef} />
      <div>
        <button type="submit" onClick={submit} disabled={!bt}>
          Submit
        </button>
      </div>
    </BasisTheoryProvider>
  );
};

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
import { useRef } from "react";
import { useBasisTheory, BasisTheoryProvider, CardNumberElement, CardExpirationDateElement, CardVerificationCodeElement, BasisTheoryValidationError, HttpClientError } from "@basis-theory/basis-theory-react";

const MyForm = () => {
  const { bt } = useBasisTheory("<API_KEY>", { elements: true }); // replace <API_KEY> w/ your public API key
  const cardNumberRef = useRef(null);
  const cardExpirationDateRef = useRef(null);
  const cardVerificationCodeRef = useRef(null);

  const submit = async () => {
    const cardNumber = cardNumberRef.current;
    const cardExpirationDate = cardExpirationDateRef.current;
    const cardVerificationCode = cardVerificationCodeRef.current;

    try {
      const response = await bt.client.patch('https://www.api.thirdpartydomain.com/resources/id', {
        number: cardNumber,
        expiration_month: cardExpirationDate.month(),
        expiration_year: cardExpirationDate.year(),
        cvc: cardVerificationCode,
        nonSensitiveData: "plainText",
      }, {
        headers: {
          'Content-Type': 'application/json',
          'Accept': 'application/json',
        },
      });

      console.log(JSON.stringify(response)); // full plaintext response
    } catch (error) {
      if (error instanceof BasisTheoryValidationError) {
        // check error details
      } else if (error instanceof HttpClientError) {
        // check error data, status, or headers
      }
    }
  };

  return (
    <BasisTheoryProvider bt={bt}>
      <CardNumberElement id="cardNumber" ref={cardNumberRef} />
      <CardExpirationDateElement id="cardExpirationDate" ref={cardExpirationDateRef} />
      <CardVerificationCodeElement id="cardVerificationCode" ref={cardVerificationCodeRef} />
      <div>
        <button type="submit" onClick={submit} disabled={!bt}>
          Submit
        </button>
      </div>
    </BasisTheoryProvider>
  );
};

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
import { useBasisTheory, BasisTheoryProvider, BasisTheoryValidationError, HttpClientError } from "@basis-theory/basis-theory-react";

const MyForm = () => {
  const { bt } = useBasisTheory("<API_KEY>", { elements: true }); // replace <API_KEY> w/ your public API key

  const submit = async () => {
    try {
      const response = await bt.client.get('https://www.api.thirdpartydomain.com/resources/id', {
        headers: {
          'Accept': 'application/json',
        },
      });

      console.log(JSON.stringify(response)); // full plaintext response
    } catch (error) {
      if (error instanceof BasisTheoryValidationError) {
        // check error details
      } else if (error instanceof HttpClientError) {
        // check error data, status, or headers
      }
    }
  };

  return (
    <BasisTheoryProvider bt={bt}>
      ...
      <div>
        <button type="submit" onClick={submit} disabled={!bt}>
          Submit
        </button>
      </div>
    </BasisTheoryProvider>
  );
};

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
import { useBasisTheory, BasisTheoryProvider, BasisTheoryValidationError, HttpClientError } from "@basis-theory/basis-theory-react";

const MyForm = () => {
  const { bt } = useBasisTheory("<API_KEY>", { elements: true }); // replace <API_KEY> w/ your public API key

  const submit = async () => {
    try {
      const response = await bt.client.delete('https://www.api.thirdpartydomain.com/resources/id', {
        headers: {
          'Accept': 'application/json',
        },
      });

      console.log(JSON.stringify(response)); // full plaintext response
    } catch (error) {
      if (error instanceof BasisTheoryValidationError) {
        // check error details
      } else if (error instanceof HttpClientError) {
        // check error data, status, or headers
      }
    }
  };

  return (
    <BasisTheoryProvider bt={bt}>
      ...
      <div>
        <button type="submit" onClick={submit} disabled={!bt}>
          Submit
        </button>
      </div>
    </BasisTheoryProvider>
  );
};

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 elements 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/basis-theory-js/common";

BasisTheory.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/basis-theory-js/common";

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

Services

Methods​

Tokenization Services​

Create Token​

Tokenize​

Token Update​

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

Tokenization Services

Create Token

Tokenize

Token Update

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