Invoke Reactors

Invoke Synchronous

Invoke a reactor by ID.

POST

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

For node22 runtime, Check valid states where it can be invoked.

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

node-bt

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("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",
    },
})

node22

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 '{
    "card": "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
    "customer_id": "myCustomerId1234"
  }'

Node

await client.reactors.react(
  reactorId,
  {
    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",
  {
    card: "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
    customer_id: "myCustomerId1234"
  }
);

C#

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

Java

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

Python

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

Go

response, err := client.Reactors.React(ctx, reactorId, &basistheory.ReactRequest{
    Card: "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
    CustomerId: "myCustomerId1234",
})

URI Parameters

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

Request Parameters

The request parameters sent depend on the runtime image chosen for the reactor:

node-bt

Parameter	Required	Type	Default	Description
args	false	object	null	Arguments to provide to the reactor. The args object will be passed to the reactor code as req.args.
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

node22

Parameter	Required	Type	Default	Description
Request body	false	object	null	Arguments to provide to the reactor. The request body is sent directly and will be passed to the reactor code as event.req. Any top-level properties in the request body become properties of event.req.

Reactor Request Parameters

Just as the request parameters vary by runtime, the parameters your reactor code receives also depend on the runtime chosen. See the Request Object section for details.

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.

For response format details, see the Response Object section.

Limitations

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

Detokenization

In order to use tokenized data within a reactor, you can include detokenization expressions in your request:

node-bt

For node-bt, include detokenization expressions within the args object:

{
  "args": {
    "card": "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
    "customer_id": "myCustomerId1234"
  }
}

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 as req.args.

node22

For node22, include detokenization expressions directly in the request body (without the args wrapper):

{
  "card": "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
  "customer_id": "myCustomerId1234"
}

When any detokenization expressions are detected, Basis Theory will attempt to detokenize and inject the raw token data into the request body, which is then passed to the Reactor function as event.req.

Request bodies 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 in the request. 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.