Use Token Data in Reactors
In this guide, we will show you how to use the pre-built Parrot BIN service Reactor Formula to take your tokenized card data and capture new analytical insights.
If you are completely new to Reactors and would like to learn more about what they are before trying them out, check out our Reactors concept page.
Table of contents
Create a Reactor
Initially, we will show you how to create a Reactor from our portal, although you can also use the Basis Theory API to replicate these steps within your own CI pipelines or code base.
Once you’re logged into the Basis Theory Portal, navigate to our Reactors page and click on “Create Reactor” on the top right to begin creating a new Reactor. On this page, you’ll see a listing of all available Reactor Formulas.
Selecting a Reactor Formula will slide out a view to explain that formula’s requirements. The Configuration section allows you to configure API keys or environment variables that remain static across Reactor invocations, while the Request Parameters section will show you the arguments you must send to the /react
endpoint each time it is invoked.
Once you find the Reactor Formula you want to create, select “Use this formula” to start creating a Reactor.
Next, you’ll be able to name and add any additional configuration to the Reactor.
That’s it! Once you’ve saved your first Reactor, you can begin interacting with it via our API.
As always, you can create the same results with the Basis Theory API to codify the creation of Reactors.
Use Your New Reactor
With your Reactor created, it’s time to start using your tokens in it. Depending on which Reactor Formula you chose to create a Reactor from, you’ll need to pass in the corresponding request parameters it needs. The Parrot Reactor Formula requires only a single parameter:
name | type | optional |
---|---|---|
card.number | string | false |
Request parameters are provided when invoking a Reactor via the args
request property. In order to satisfy the request parameter contract defined on the Reactor Formula, you may supply any mixture of constant values and detokenization expressions within args
.
Next, we’ll walk through a couple ways in which you could invoke the Parrot reactor to provide the card number depending on how you chose to tokenize your card data.
To run a Reactor, an application needs token:<classification>:use:reactor
permission for any tokens that are detokenized. For these examples you will need an application with token:pci:use:reactor
permission. Click here to create one.
In each of the following examples, on a successful request you will be returned a React Response which contains data returned from your executed Reactor.
{
"tokens": "<Tokenized Data Returned from the Reactor>",
"raw": "<Raw Output Returned from the Reactor>"
}
Use a Card Number Token
In the following example we have opted to store the card number within a Card Number Token. We will include a detokenization expression containing this token in the Reactor request, which will result in the original token data being inserted within the request sent to the Reactor.
curl "https://api.basistheory.com/reactors/<reactor_id>/react" \
-H "BT-API-KEY: <application_api_key>" \
-X "POST" \
-d '{
"args": {
"card": {
"number": "{{<card_number_token_id>}}"
}
}
}'
Use a Card Token
In the following example we have opted to store the card data within a Card Token. Since the data within a Card token contains a number
property, we can simply detokenize the entire Card token into the card
argument, which will cause the token’s entire JSON object data to be inserted into the card
node.
curl "https://api.basistheory.com/reactors/<reactor_id>/react" \
-H "BT-API-KEY: <application_api_key>" \
-X "POST" \
-d '{
"args": {
"card": "{{<card_token_id>}}"
}
}'
Since Reactors validate the provided args
against the declared request parameters and drop any undeclared arguments, the additional properties (expiration_month
, expiration_year
, cvc
) on the Card token object will be automatically removed from the request.
Use a Card Token with a JSON Path Transformation
In the following example we have again opted to store the card data within a Card Token. However, in this example we will pass only the number
property from the Card token by using a JSON Path Transformation to project out the number
property.
curl "https://api.basistheory.com/reactors/<reactor_id>/react" \
-H "BT-API-KEY: <application_api_key>" \
-X "POST" \
-d '{
"args": {
"card": {
"number": "{{ <card_token_id> | $.number }}"
}
}
}'