Services

Basis Theory React Native Elements SDK provides several methods and services for safely collecting, sharing, or manipulating sensitive data.

Initialization

  import { useBasisTheory } from "@basis-theory/basis-theory-react-native";
  ...
  const { bt } = useBasisTheory('<PUBLIC API KEY>');

Ensure you initialize the Basis theory SDK just once and share the same bt object across your app to avoid inconsistent behavior.

Tokens

Create a token

This function wraps the create a token API endpoint to generate a single token.

const { bt } = useBasisTheory("<PUBLIC API KEY>");

const token = await bt?.tokens.create({
  type: "card",
  data: {
    number: cardNumberRef.current,
    expiration_month: cardExpirationRef.current.month(),
    expiration_year: cardExpirationRef.current.year(),
    cvc: cardVerificationRef.current,
  },
});

Our elements will encapsulate the sensitive data allowing your users to modify the element values without your application directly interacting with it, thereby ensuring compliance within your application.

For detailed instructions on creating tokens with react native, please refer to our guide on collecting cards.

Tokenize

This function wraps the tokenize API endpoint to create tokens out of any request and create tokens of different types of tokens in the same request.

const { bt } = useBasisTheory("<PUBLIC API KEY>");

const token = await bt?.tokens.tokenize({
  first_name: "John",
  last_name: "Doe",
  primary_card: {
    type: "card",
    data: {
      number: cardNumberRef.current,
      expiration_month: cardExpirationRef.current.month(),
      expiration_year: cardExpirationRef.current.year(),
      cvc: cardVerificationRef.current,
    },
  },
  secondary_card: {
    type: "card",
    data: {
      number: cardNumberRef1.current,
      expiration_month: cardExpirationRef1.current.month(),
      expiration_year: cardExpirationRef1.current.year(),
      cvc: cardVerificationRef1.current,
    },
  },
  sensitive_tags: [
    "preferred",
    {
      type: "token",
      data: "vip",
    },
  ],
});

Retrieve a token and display its data

This function wraps the get a token API endpoint, enabling you to fetch a single token by its id.

const { bt } = useBasisTheory("<PUBLIC API KEY>");

const token = await bt?.tokens.retrieve("<TOKEN ID>", <OPTIONAL SESSION KEY>);

If the the optional session key is not passed to bt.tokens.retrieve, the function will return a token object that does not contain any sensitive data.

The data attribute in the token returned by the retrieve method is not the actual data, but 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.

Revealing token data

It's important to note that accessing sensitive data requires creating and authorizing a session, and bt.tokens.retrieve takes in its corresponding sessionKey for secure retrieval of such information.

Once the token data is retrieved, the SDK encapsulates the data into an InputBTRef. This reference can then be utilized to set an element's value. This approach ensures that element values can be displayed without direct interaction with sensitive data, thus maintaining compliance within the application's scope.

Here's how to structure your code to create a session:

const { bt } = useBasisTheory("<PUBLIC API KEY>");

const session = await bt?.sessions.create();

For detailed information on the CreateSessionResponse object, please refer to our API documentation.

The newly created session needs authorization from a private application before you can reveal the token value. Your backend must perform the authorization call.

For detailed instructions on constructing the session authorization request, please refer to our guide on displaying cards.

import React, { useRef } from "react";
import { Button } from "react-native";
import { CardNumberElement, BTRef } from "@basis-theory/basis-theory-react-native";

const MyForm = () => {
  const { bt } = useBasisTheory("<PUBLIC API KEY>");

  const cardNumberRef = useRef<BTRef>(null);

  const getCardNumber = async () => {
    // create the session
    const session = await bt?.sessions.create();

    // authorize the session
    await fetch("< YOUR_BT_SESSION_AUTH_ENDPOINT >", {
      method: "POST",
      headers: {
        Accept: "application/json",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        nonce: session?.nonce,
        tokenId,
      }),
    });

    const token = await bt?.tokens.retrieve("<YOUR TOKEN ID>", session?.sessionKey);

    cardNumberRef.current.setValue(token.data.number);
  };

  return (
    <>
      <CardNumberElement btRef={cardNumberRef} placeholder="Card Number" />
      <div>
        <Button type="button" onPress={getCardNumber} />
      </div>
    </>
  );
};

Update a token

This function wraps the update token API endpoint to update a single token.

const { bt } = useBasisTheory("<PUBLIC API KEY>");

const token = await bt?.tokens.update("<TOKEN ID>", {
  data: {
    number: cardNumberRef.current,
    expiration_month: cardExpirationRef.current.month(),
    expiration_year: cardExpirationRef.current.year(),
  },
});

Delete a token

This function wraps the delete token API endpoint to delete a single token.

const { bt } = useBasisTheory("<PUBLIC API KEY>");

await bt?.tokens.delete("<TOKEN ID>");

The Basis Theory React Native SDK repository contains code examples demonstrating the implementation of each of the aforementioned methods, adhering to best practices.

Proxy

Proxy provides a simple way to retrieve data back into an element utilizing our proxy service.

const { bt } = useBasisTheory('<PUBLIC API KEY>');

const proxyResponse = await bt?.proxy({
  headers: {
    'BT-API-KEY': '<SESSION_API_KEY>',
    'BT-PROXY-KEY': '<YOUR API KEY>',
    'Content-Type': 'application/json',
  },
  body: {...},
  method: 'post',
  path: '/my-proxy',
  query: {
      query1: 'value1',
      query2: 'value2',
  },
});

Parameters

Parameter	Type	Required	Description
method	string	true	The HTTP method to invoke for the proxy request ("post", "put", "patch", "get", "delete")
headers	object	false	The headers to pass into the proxy request
body	object	false	The request body to pass into the proxy request
query	object	false	The query params to pass into the proxy request
path	string	false	The path to pass onto the end of the proxy destination URL

The response returns a proxu. All values in the response is converted to an InputBTRef. This means that you can traverse through the proxy response and set the value of your elements without touching the plaintext value. Below is an example of how to do that.

import React, { useRef } from "react";
import { CardNumberElement, CardExpirationDateElement, CardVerificationCodeElement, BasisTheoryElements, BTRef } from "@basis-theory/basis-theory-react-native";

const MyForm = () => {
  const { bt } = useBasisTheory("<PUBLIC API KEY>");

  const cardNumberRef = useRef<BTRef>(null);
  const cardExpirationDateRef = useRef<BTRef>(null);
  const cardVerificationCodeRef = useRef<BTRef>(null);

  const getCardData = async () => {
    const proxyResponse = await bt?.proxy({
      headers: {
        "BT-API-KEY": "<SESSION_API_KEY>",
        "BT-PROXY-KEY": "<YOUR PROXY KEY>",
      },
      method: "post",
    });

    cardNumberRef.current?.setValue(proxyResponse.json.cardNumber);
    cardExpirationDateRef.current?.setValue(proxyResponse.json.expDate);
    cardVerificationCodeRef.current?.setValue(proxyResponse.json.cvc);
  };

  return (
    <>
      <CardNumberElement btRef={cardNumberRef} placeholder="Card Number" />
      <CardExpirationDateElement btRef={cardExpirationDateRef} placeholder="Card Expiration Date" />
      <CardVerificationCodeElement btRef={cardVerificationCodeRef} placeholder="CVC" />
      <div>
        <button type="button" onClick={getCardData}>
          "Get Card Data"
        </button>
      </div>
    </>
  );
};