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>');
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.
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.
data
attribute in the token returned by the retrieve
method is not the actual data, but a synthetic representation of the sensitive detokenized data.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();
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.
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>");
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>
</>
);
};