Invoke Async Reactors

Invoke Asynchronously

Enterprise

Invoke a reactor by ID asynchronously. See Asynchronous Reactors for more info.

POST

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

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-async" \
  -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.reactAsync(
  reactorId,
  {
    args: {
      card "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
      customer_id: "myCustomerId1234"
    }
  }
);

C#

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

Python

client.reactors.react_async(
    id=reactor_id,
    args={
      "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.

Response

{
    "asyncReactorRequestId": "3254626a-e1cf-4616-968f-e08a7ade4fce"
}

Returns a request ID that can be used later to retrieve the results of the asynchronous invocation.

Retrieve Async Result

Enterprise

Will retrieve the results of an asynchronous invocation.

GET

https://api.basistheory.com/reactors/{id}/results/{request_id}

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 --location 'https://api.basistheory.com/reactors/7001A144-96D0-4401-9D96-13557824A9E0/results/369a879e-338d-4f52-83cf-53a6af3f3f18' \
--header 'BT-API-KEY: <PRIVATE_API_KEY>'

Node

await client.reactors.results.get("id", "requestId");

C#

await client.Reactors.Results.GetAsync("id", "requestId");

Python

client.reactors.results.get(
    id="id",
    request_id="requestId",
)

Java

new ReactorsClient(ClientOptions.builder().build()).results().get("id", "requestId");

Go

response, err := client.Reactors.Results.Get(ctx, "reactorId", "requestId")

URI Parameters

Parameter	Required	Type	Default	Description
id	true	uuid	null	The ID of the Reactor
request_id	true	uuid	null	The ID of the Reactor request id. Retrieved from either the response of react-async or from the webhook events (reactor.invoked, reactor.completed, reactor.failed).

Request Parameters

Parameter	Required	Type	Default	Description
args	false	object	null	Arguments to provide to 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.