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

1. Create a Reactor
2. Use Your New Reactor
   1. Use a Card Number Token
   2. Use a Card Token
   3. Use a Card Token with a JSON Path Transformation

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:

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 the json filter 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> | json: '$.number' }}"
      }
    }
  }'