Skip to main content

Reactor Formulas

Reactor formulas give you the ability to pre-configure custom integrations to securely process, enrich, and associate your tokens.

Create Reactor Formula

Create a new Reactor Formula for the Tenant.

POST https://api.basistheory.com/reactor-formulas
Copy

Permissions

reactor:create

Request

curl "https://api.basistheory.com/reactor-formulas" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"name": "My Private Reactor",
"description": "Securely react a token for another token",
"type": "private",
"icon": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"code": "
module.exports = async function (req) {
// Do something with `req.configuration.SERVICE_API_KEY`

return {
raw: {
foo: 'bar'
}
};
};
",
"configuration": [
{
"name": "SERVICE_API_KEY",
"description": "Configuration description",
"type": "string"
}
],
"request_parameters": [
{
"name": "request_parameter_1",
"description": "Request parameter description",
"type": "string"
},
{
"name": "request_parameter_2",
"description": "Request parameter description",
"type": "boolean",
"optional": true
}
]
}'

Request Parameters

AttributeRequiredTypeDefaultDescription
nametruestringnullThe name of the Reactor Formula. Has a maximum length of 200
descriptionfalsestringnullThe description of the Reactor Formula
typetruestringnullType of the Reactor Formula
iconfalsestringnullBase64 data URL of the image. Supported image types are: image/png, image/jpg, and image/jpeg
codetruestringnullReactor code which will be executed when the Reactor Formula is processed
configurationtruearray[]Array of configuration options for configuring a Reactor
request_parameterstruearray[]Array of request parameters which will be passed when executing the Reactor

Response

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

{
"id": "17069df1-80f4-439e-86a7-4121863e4678",
"name": "My Private Reactor",
"description": "Securely exchange token for another token",
"type": "private",
"icon": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"code": "
module.exports = async function (req) {
// Do something with `req.configuration.SERVICE_API_KEY`

return {
raw: {
foo: 'bar',
}
};
};
",
"configuration": [
{
"name": "SERVICE_API_KEY",
"description": "Configuration description",
"type": "string"
}
],
"request_parameters": [
{
"name": "request_parameter_1",
"description": "Request parameter description",
"type": "string"
},
{
"name": "request_parameter_2",
"description": "Request parameter description",
"type": "boolean",
"optional": true
}
],
"created_by": "c57a0d0d-e8e6-495f-9c79-a317cc21996c",
"created_at": "2020-09-15T15:53:00+00:00"
}

List Reactor Formulas

Get a list of official Reactor Formulas and private Tenant-specific Reactor Formulas.

GET https://api.basistheory.com/reactor-formulas
Copy

Permissions

reactor:read

Request

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

Query Parameters

ParameterRequiredTypeDefaultDescription
namefalsestringnullWildcard search of Reactor Formulas by name

Response

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

{
"pagination": {...}
"data": [
{
"id": "17069df1-80f4-439e-86a7-4121863e4678",
"name": "My Private Reactor",
"description": "Securely exchange token for another token",
"type": "private",
"icon": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"code": "
module.exports = async function (req) {
// Do something with `req.configuration.SERVICE_API_KEY`

return {
raw: {
foo: 'bar'
}
};
};
",
"configuration": [
{
"name": "SERVICE_API_KEY",
"description": "Configuration description",
"type": "string"
}
],
"request_parameters": [
{
"name": "request_parameter_1",
"description": "Request parameter description",
"type": "string"
},
{
"name": "request_parameter_2",
"description": "Request parameter description",
"type": "boolean",
"optional": true
}
],
"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 Formula

Get a Reactor Formula by ID in the Tenant.

GET https://api.basistheory.com/reactor-formulas/{id}
Copy

Permissions

reactor:read

Request

curl "https://api.basistheory.com/reactor-formulas/17069df1-80f4-439e-86a7-4121863e4678" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe ID of the Reactor Formula

Response

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

{
"id": "17069df1-80f4-439e-86a7-4121863e4678",
"name": "My Private Reactor",
"description": "Securely exchange token for another token",
"type": "private",
"icon": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"code": "
module.exports = async function (req) {
// Do something with `req.configuration.SERVICE_API_KEY`

return {
raw: {
foo: 'bar',
}
};
};
",
"configuration": [
{
"name": "SERVICE_API_KEY",
"description": "Configuration description",
"type": "string"
}
],
"request_parameters": [
{
"name": "request_parameter_1",
"description": "Request parameter description",
"type": "string"
},
{
"name": "request_parameter_2",
"description": "Request parameter description",
"type": "boolean",
"optional": true
}
],
"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 Formula

Update a Reactor Formula by ID in the Tenant.

PUT https://api.basistheory.com/reactor-formulas/{id}
Copy

Permissions

reactor:update

Request

curl "https://api.basistheory.com/reator-formula/17069df1-80f4-439e-86a7-4121863e4678" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
-H "Content-Type: application/json" \
-X "PUT" \
-d '{
"name": "My Private Reactor",
"description": "Securely exchange token for another token",
"type": "private",
"icon": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"code": "
module.exports = async function (req) {
// Do something with `req.configuration.SERVICE_API_KEY`

return {
raw: {
foo: 'bar'
}
};
};
",
"configuration": [
{
"name": "SERVICE_API_KEY",
"description": "Configuration description",
"type": "string"
}
],
"request_parameters": [
{
"name": "request_parameter_1",
"description": "Request parameter description",
"type": "string"
},
{
"name": "request_parameter_2",
"description": "Request parameter description",
"type": "boolean",
"optional": true
}
]
}'

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe ID of the Reactor Formula

Request Parameters

AttributeRequiredTypeDefaultDescription
nametruestringnullThe name of the Reactor Formula. Has a maximum length of 200
descriptionfalsestringnullThe description of the Reactor Formula
typetruestringnullType of the Reactor Formula
iconfalsestringnullBase64 data URL of the image. Supported image types are: image/png, image/jpg, and image/jpeg
codetruestringnullReactor code which will be executed when the Reactor Formula is processed
configurationtruearray[]Array of configuration options for configuring a Reactor
request_parameterstruearray[]Array of request parameters which will be passed when executing the Reactor

Response

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

{
"id": "17069df1-80f4-439e-86a7-4121863e4678",
"name": "My Private Reactor",
"description": "Securely exchange token for another token",
"type": "private",
"icon": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"code": "
module.exports = async function (req) {
// Do something with `req.configuration.SERVICE_API_KEY`

return {
raw: {
foo: 'bar',
}
};
};
",
"configuration": [
{
"name": "SERVICE_API_KEY",
"description": "Configuration description",
"type": "string"
}
],
"request_parameters": [
{
"name": "request_parameter_1",
"description": "Request parameter description",
"type": "string"
},
{
"name": "request_parameter_2",
"description": "Request parameter description",
"type": "boolean",
"optional": true
}
],
"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"
}

Delete Reactor Formula

Delete a Reactor Formula by ID in the Tenant.

DELETE https://api.basistheory.com/reactor-formulas/{id}
Copy

Permissions

reactor:delete

Request

curl "https://api.basistheory.com/reactor-formulas/17069df1-80f4-439e-86a7-4121863e4678" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
-X "DELETE"

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe ID of the Reactor Formula

Response

Returns an error if the Reactor Formula failed to delete.

Reactor Formula Object

AttributeTypeDescription
iduuidUnique identifier of the Reactor Formula which can be used to get a Reactor Formula
namestringThe name of the Reactor Formula. Has a maximum length of 200
descriptionstringThe description of the Reactor Formula
typestringType of the Reactor Formula
statusstringStatus of the Reactor Formula
iconstringBase64 data URL of the image
codestringReactor Formula code which will be executed when the Reactor Formula is processed
configurationarrayArray of configuration options for configuring a reactor
request_parametersarrayArray of request parameters which will be passed when executing the reactor
created_atdate(Optional) Created date of the Reactor Formula in ISO 8601 format
created_byuuid(Optional) The ID of the user or Application that created the Reactor Formula
modified_atdate(Optional) Last modified date of the Reactor Formula in ISO 8601 format
modified_byuuid(Optional) The ID of the user or Application that last modified the Reactor Formula

Reactor Formula Configuration

The configuration property of a Reactor Formula defines the contract that the configuration property must satisfy on all Reactors created from this formula. Elements of a Reactor Formula's configuration array have the following schema:

AttributeRequiredTypeDefaultDescription
nametruestringnullName of the configuration setting
descriptionfalsestringnullDescription of the configuration setting
typetruestringnullData type of the configuration setting. Valid values are string, boolean, and number

Reactor configuration is intended for properties that can be defined once per Reactor and do not change between Reactor invocations. Complex nested objects (dot-separated names) are not currently supported within a Reactor's configuration.

Reactor Formula Request Parameters

The request_parameters array on a Reactor Formula defines the contract that the args property must satisfy on each request when Invoking a Reactor. Elements of a Reactor Formula's request_parameters array have the following schema:

AttributeRequiredTypeDefaultDescription
nametruestringnullName of the request parameter. Complex objects can be denoted as [parent].[child]
descriptionfalsestringnullDescription of the request parameter
typetruestringnullData type of the request parameter. Valid values are string, boolean, and number
optionalfalsebooleanfalseIf the request parameter is optional when executing the reactor

Request parameters are intended to define any parameters that will be provided to a Reactor at request-time, and may change across Reactor invocations. Complex objects properties can be passed within the args property to a Reactor, and they can be defined by dot-separating levels of the object hierarchy.

Any args property not associated with a request parameter is still forwarded to the reactor. This allows you to provide complete complex objects including arrays, in which no type checking is applied. For instance, if no request parameters are declared, it means you can provide any payload when invoking the reactor.

Reactor Formula Code

All Reactor Formula code snippets must export a function which takes in a request object and returns a response object.

Reactor Formula Request Object

AttributeTypeDescription
argsobjectThe arguments that were provided when the reactor was invoked
configurationobjectThe configuration defined for the Reactor object

Reactor Formula Response Object

AttributeTypeDescription
rawobject(Optional) Raw output returned from the Reactor
tokenizeobject(Optional) A payload that will be tokenized to produce one or more tokens

The payload returned in the tokenize property will be tokenized in the same way that requests are tokenized via the Tokenize endpoint. For more information, see Tokenize.

Reactor Formula Code is written in Javascript (targeting Node.js v16) and generally follows the structure:

module.exports = async function (req) {
const { my_arg } = req.args; // access any args provided with the request
const { MY_CONFIG } = req.configuration; // access any static config defined on the Reactor

// do anything here!

return {
raw: {}, // non-sensitive data that should be returned in plaintext
tokenize: {}, // sensitive data that should be tokenized
};
};

For more information about writing your own code for a Reactor Formula, check out our guide.

Reactor Formula Types

TypeDescription
officialOfficial formulas that are built and supported by Basis Theory and its authorized partners
privatePrivate formulas which are only available to your Tenant

Reactor Formula Statuses

TypeDescription
verifiedThe formula has been verified and is generally available
coming_soonThe formula has limited availability. Request to join the Private Beta for access.