Invoke Reactors

Invoke Synchronous

Invoke a reactor by ID.

POST

https://api.basistheory.com/reactors/{id}/react

Permissions

reactor:invoke

For existing reactors and to maintain backward compatibility we are also supporting token:use, however we recommend updating the permissions since that will be deprecated soon.

Request

cURL

curl "https://api.basistheory.com/reactors/5b493235-6917-4307-906a-2cd6f1a90b13/react" \
  -H "BT-API-KEY: <PRIVATE_API_KEY>" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "args": {
      "card": "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
      "customer_id": "myCustomerId1234"
    }
  }'

Node

await client.reactors.react(
  reactorId,
  {
    args: {
      card: "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
      customer_id: "myCustomerId1234"
    }
  }
);

JavaScript (legacy)

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<PRIVATE_API_KEY>");

const reactResponse = await bt.reactors.react(
  "5b493235-6917-4307-906a-2cd6f1a90b13",
  {
    args: {
      card: "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
      customer_id: "myCustomerId1234",
    },
  }
);

C#

await client.Reactors.ReactAsync(
  reactorId,
  new ReactRequest
  {
    Args = new
    {
      card = "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
      customer_id = "myCustomerId1234"
    }
  }
);

Java

new ReactorsClient(ClientOptions.builder().build()).react("id", ReactRequest.builder()
    .args(new HashMap() {{
        put("args", new HashMap() {{
            put("card", "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}");
            put("customer_id", "myCustomerId1234");
        }});
    }})
    .build());

Python

client.reactors.react(
    id=reactor_id,
    args={
      "card": "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
      "customer_id": "myCustomerId1234"
    }
)

Go

response, err := client.Reactors.React(ctx, reactorId, &basistheory.ReactRequest{
    Args: map[string]interface{}{
        "card": "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
        "customer_id": "myCustomerId1234",
    },
})

URI Parameters

Parameter	Required	Type	Default	Description
id	true	uuid	null	The ID of the Reactor

Request Parameters

Parameter	Required	Type	Default	Description
args	false	object	null	Arguments to provide to the reactor.
callback_url	false	string	null	Indicates that the reactor should be invoked asynchronously and the result delivered as a webhook to this URL. See Asynchronous Reactors for more info. Enterprise DEPRECATED

Reactor Request Parameters

The reactor will be executed with a req object that contains the following properties

Parameter	Description
args	Detokenized arguments to provided to the reactor.
configuration	A string key and string value map of all configuration name and values defined when creating the Reactor
bt	A pre-configured Basis Theory JS instance for the application defined with the Reactor. This will be null if no application was defined.

Response

Returns a Reactor Response if the Reactor completed successfully. Returns an error if the Reactor failed. Errors generated from Reactors will be translated to the common Basis Theory Error format. See Reactor Error Codes below for more details.

Reactor Response Object

Attribute	Type	Description
tokens	object	(Optional) Token(s) created from the tokenize block of the Reactor code response
raw	object	(Optional) Raw output returned from the Reactor

Limitations

Head over to Rate Limits to learn more about Reactors limitations.

Detokenization

In order to use tokenized data within a reactor, the args parameter may contain one or more detokenization expressions. When any detokenization expressions are detected, Basis Theory will attempt to detokenize and inject the raw token data into the args forwarded to the Reactor function.

Reactor request args may contain a mixture of detokenization expressions and raw plaintext data.

Tokens containing complex data may be detokenized into a Reactor request, including Bank and Card token types. When tokens with complex data are detokenized, the entire JSON data payload will be included within the args. For an example, see Use Complex Tokens.

Validation is performed on the resulting request after detokenization, so several required request parameters may be supplied by detokenizing a single complex token that contains several of the request parameters.

At most, 100 tokens may be detokenized within a single Reactor request.

For more detailed examples about how to detokenize within Reactors, check out our Detokenization Examples.

Reactor Error Codes

Code	Meaning	Common Scenarios
400	Bad Request	Missing or invalid args on the request Invalid Reactor Configuration
401	Authentication Error	Invalid or unknown credentials Credentials are valid, but lack permission to complete the operation
402	Invalid Payment Method	Expired Card A test card or bank account was used in a production environment, or vice-versa An external API denied the card or bank account
422	Unprocessable Entity	Reactor code is not a valid function
429	Rate Limit Error	An external API responded with a 429 HTTP response code
500	Reactor Runtime Error	An unhandled exception occurred An external API responded with a 5XX HTTP response code External API connection failure

There are a few different root causes for why one of these errors may be returned from a reactor:

1. An error occurred within Basis Theory's reactor execution framework when processing your request. For example, this can occur if the reactor code is invalid and fails to compile (JavaScript code is validated before being executed) resulting in a 422 error, or if the provided args contain an invalid expression resulting in a 400 error.

2. An error occurred within your reactor code. For example, an HTTP call is made to an external API and they responded with an error, or a runtime error occurred within the code due to a bug. The following section details best practices when handling errors within reactor code.