Skip to main content

Reactors

Create Reactor

Create a new Reactor from a Reactor Formula for the Tenant.

POST
https://api.basistheory.com/reactors
Copy

Permissions

reactor:create

Request

curl "https://api.basistheory.com/reactors" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"name": "My Reactor",
"configuration": {
"SERVICE_API_KEY": "key_abcd1234"
},
"formula": {
"id": "17069df1-80f4-439e-86a7-4121863e4678"
},
"application": {
"id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
}
}'

Request Parameters

AttributeRequiredTypeDefaultDescription
nametruestringnullThe name of the reactor. Has a maximum length of 200
configurationtrueobjectnullA key-value map of all configuration name and values for a Reactor Formula configuration
formula.idtrueuuidnullUnique identifier of the Reactor Formula to configure a Reactor for
application.idfalseuuidnullThis Application's API key is injected into a pre-configured BasisTheory JS SDK instance passed into the Reactor's runtime. Must be a public or private Application Type.

The configuration object must satisfy the name and type constraints defined by the Reactor Formula's configuration property.

Response

Returns a Reactor if the Reactor was created. Returns an error if there were validation errors, or the Reactor failed to create.

{
"id": "5b493235-6917-4307-906a-2cd6f1a90b13",
"tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
"name": "My Reactor",
"formula": {...},
"application": {...},
"configuration": {
"SERVICE_API_KEY": "key_abcd1234"
},
"created_by": "3ce0dceb-fd0b-4471-8006-c51243c9ef7a",
"created_at": "2020-09-15T15:53:00+00:00"
}

List Reactors

Get a list of reactors for the Tenant.

GET
https://api.basistheory.com/reactors
Copy

Permissions

reactor:read

Request

curl "https://api.basistheory.com/reactors" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Query Parameters

ParameterRequiredTypeDefaultDescription
idfalsearray[]An optional list of Reactor ID's to filter the list of reactors by
namefalsestringnullWildcard search of reactors by name

Response

Returns a paginated object with the data property containing an array of reactors. Providing any query parameters will filter the results. Returns an error if reactors could not be retrieved.

{
"pagination": {...}
"data": [
{
"id": "5b493235-6917-4307-906a-2cd6f1a90b13",
"tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
"name": "My Reactor",
"formula": {...},
"configuration": {
"SERVICE_API_KEY": "key_abcd1234"
},
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2020-09-15T15:53:00+00:00",
"modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"modified_at": "2021-03-01T08:23:14+00:00"
},
{...},
{...}
]
}

Get a Reactor

Get a Reactor by ID in the Tenant.

GET
https://api.basistheory.com/reactors/{id}
Copy

Permissions

reactor:read

Request

curl "https://api.basistheory.com/reactors/5b493235-6917-4307-906a-2cd6f1a90b13" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe ID of the reactor

Response

Returns a Reactor with the id provided. Returns an error if the Reactor could not be retrieved.

{
"id": "5b493235-6917-4307-906a-2cd6f1a90b13",
"tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
"name": "My Reactor",
"formula": {...},
"configuration": {
"SERVICE_API_KEY": "key_abcd1234"
},
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2020-09-15T15:53:00+00:00",
"modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"modified_at": "2021-03-01T08:23:14+00:00"
}

Update Reactor

Update a Reactor by ID in the Tenant.

PUT
https://api.basistheory.com/reactors/{id}
Copy

Permissions

reactor:update

Request

curl "https://api.basistheory.com/reactors/5b493235-6917-4307-906a-2cd6f1a90b13" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
-H "Content-Type: application/json" \
-X "PUT" \
-d '{
"name": "My Reactor",
"configuration": {
"SERVICE_API_KEY": "key_abcd1234"
},
"application": {
"id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
}
}'

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe ID of the reactor

Request Parameters

AttributeRequiredTypeDefaultDescription
nametruestringnullThe name of the reactor. Has a maximum length of 200
configurationtrueobjectnullA key-value map of all configuration name and values for a Reactor Formula configuration
application.idfalseuuidnullThis Application's API key is injected into a pre-configured BasisTheory JS SDK instance passed into the Reactor's runtime. Must be a public or private Application Type.

Response

Returns a Reactor if the Reactor was updated. Returns an error if there were validation errors, or the Reactor failed to update.

{
"id": "5b493235-6917-4307-906a-2cd6f1a90b13",
"tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
"name": "My Reactor",
"formula": {...},
"configuration": {
"SERVICE_API_KEY": "key_abcd1234"
},
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2020-09-15T15:53:00+00:00",
"modified_by": "34053374-d721-43d8-921c-5ee1d337ef21",
"modified_at": "2021-03-01T08:23:14+00:00"
}

Patch Reactor

Patch a Reactor by ID in the Tenant.

PATCH
https://api.basistheory.com/reactors/{id}
Copy

Permissions

reactor:update
The Patch Reactors endpoint uses a different content-type to support merge-patch operations. Requests need the Content-Type header to be set to application/merge-patch+json. Requests made with a different Content-Type header value will receive a 415 Unsupported Media Type response code. For more information on merge-patch, see RFC 7386.

Request

curl "https://api.basistheory.com/reactors/5b493235-6917-4307-906a-2cd6f1a90b13" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
-H "Content-Type: application/merge-patch+json" \
-X "PATCH" \
-d '{
"name": "My Reactor",
"configuration": {
"SERVICE_API_KEY": "key_abcd1234"
}
}'

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe ID of the reactor

Request Parameters

AttributeRequiredTypeDefaultDescription
namefalsestringnullThe name of the reactor. Has a maximum length of 200
configurationfalseobjectnullA key-value map of all configuration name and values for a Reactor Formula configuration
application.idfalseuuidnullThis Application's API key is injected into a pre-configured BasisTheory JS SDK instance passed into the Reactor's runtime. Must be a public or private Application Type.

Response

Returns 204 if successful. Returns an error if there were validation errors, or the operation failed.

Delete Reactor

Delete a Reactor by ID in the Tenant.

DELETE
https://api.basistheory.com/reactors/{id}
Copy

Permissions

reactor:delete

Request

curl "https://api.basistheory.com/reactors/fb124bba-f90d-45f0-9a59-5edca27b3b4a" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
-X "DELETE"

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe ID of the reactor

Response

Returns an error if the Reactor failed to delete.

Invoke a Reactor

Invoke a reactor by ID.

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

Permissions

token:use

The token:use permission is required to use a Reactor, and it is required for each Container of Tokens you wish to detokenize in a Reactor.

The maximum payload size to invoke a Reactor is 5 MB. You could pull in more data using the injected BT client from within the Reactor code. Please reach out if you need help.

Request

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

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe ID of the Reactor

Request Parameters

ParameterRequiredTypeDefaultDescription
argsfalseobjectnullArguments to provide to the reactor. These are required when arguments have been defined as request parameters on a Reactor Formula.
callback_urlfalsestringnullIndicates that the reactor should be invoked asynchronously and the result delivered as a webhook to this URL. See Asynchronous Reactors for more info.
timeout_msfalseint10000The maximum execution time for the reactor. Value must be between 10000 (10s) and 210000 (3.5m). Only supported for Asynchronous Reactors requests.

Reactor Request Parameters

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

ParameterDescription
argsDetokenized arguments to provided to the reactor.
configurationA key-value map of all configuration name and values when creating the Reactor
btA 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 Errors for more details.

Reactor Response Object

AttributeTypeDescription
tokensobject(Optional) Token(s) created from the tokenize block of the Reactor Formula response
rawobject(Optional) Raw output returned from the Reactor

Validation

When invoking a reactor, you may provide any args within your request without first pre-declaring request_parameters within the Reactor Formula. However, if the formula declares any request_parameters, then matching args will be validated against this contract. Argument validation occurs when a property within args exactly matches the name of a request parameter - this comparison is case-sensitive. Additional arguments included within args that are not declared as request parameters will not be validated and will be passed into the reactor.

Nested objects may be declared as request parameters by dot-separating levels of the object hierarchy. For example, we may have a Reactor Formula with complex request parameters declared as:

nametypeoptional
request_idstringfalse
user.first_namestringfalse
user.last_namestringfalse
user.address.citystringtrue
user.address.statestringtrue

Then the following arguments would constitute a valid Reactor request:

{
"args": {
"request_id": "d29e8a27-bfdb-4d26-9f13-29bdeafc9bfe",
"user": {
"first_name": "John",
"last_name": "Doe",
"address": {
"city": "Seattle",
"state": "WA"
}
}
}
}

All required request_parameters (those with optional: false) must be included within the args on each request or the request will be rejected with a 400 error. If a request parameter is declared as optional, then a value for this parameter may be omitted within args.

Each validated argument must match the type on the corresponding request parameter, and if the type does not match, auto casting to the declared type will be attempted. For example, say a request parameter is declared with type number but the string value "123" is provided. This value can be cast to a number, so the reactor would receive the numeric value 123. However, if the string value "non-numeric" were provided, a 400 error would be returned because the value cannot be cast to a number. If an expression is provided within the args for a declared request parameter, then auto type casting is performed after detokenization.

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.

If the args passed into a Reactor contain additional properties that have not been declared as request parameters on the Reactor Formula, those properties will be automatically removed and not sent on the request to the Reactor function.

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 Object

AttributeTypeDescription
iduuidUnique identifier of the Reactor which can be used to get a Reactor
tenant_iduuidThe Tenant ID which owns the reactor
namestringThe name of the reactor
formulaReactor FormulaReactor Formula this Reactor is configured for
configurationmapA key-value map of all configuration name and values for a Reactor Formula configuration
applicationApplication(Optional) This Application's API key is injected into a pre-configured BasisTheory JS SDK instance passed into the Reactor's runtime. Must be a public or private Application Type.
created_byuuid(Optional) The ID of the user or Application that created the Reactor
created_atstring(Optional) Created date of the Reactor in ISO 8601 format
modified_byuuid(Optional) The ID of the user or Application that last modified the Reactor
modified_atdate(Optional) Last modified date of the Reactor in ISO 8601 format