Routing profiles

Define how Tokeflow routes each transaction — routing profiles, their ordered rule nodes, the default connector, and the fallback order behind cascade.

A routing profile is the rule set Tokeflow evaluates when deciding which connected provider should attempt a charge. It holds an ordered list of nodes — each node matches on conditions such as payment method, card brand, country, or currency, and points at the connector that should handle the matches. When no node matches, the profile's default connector takes the charge.

Order is the whole point: nodes are evaluated top to bottom, and their order also defines the fallback chain that makes cascade work. When an attempt fails with a retryable decline, Tokeflow moves to the next eligible node instead of returning a failure. See How Tokeflow works for the orchestration model, and Connectors for the provider connections these rules point at.

Reordering nodes changes live routing for the next transaction. Change the order in a low-traffic window, then confirm the result on a transaction's timeline — it records which node produced each attempt in applied_routing_rule_id.

The routing profile object

A routing profile and its nodes, as returned by the list and retrieve endpoints.

Field	Type	Description
`id`	string	Routing profile ID.
`merchant_id`	string	Merchant ID.
`name`	string	Routing profile name.
`created_at`	string	Routing profile creation timestamp. (ISO 8601 UTC).
`updated_at`	string	Routing profile last update timestamp. (ISO 8601 UTC).
`is_active`	boolean	Whether the routing profile is active.
`version`	number	Routing profile version.
`payment_method`	string	Payment method scope.
`default_merchant_connector_id`	string \| null	Default connector ID used when no rule node matches.

Endpoints

GET`/api/v1/merchants/:merchant_id/routing-profiles`

OrgMerchant

Auth: Organization key (with merchant_id) or Merchant key.

A routing profile holds a decision tree that picks which connector handles a payment, plus a default connector to fall back on.

Path parameters

Field	Type	Required	Description
`merchant_id`	string	Yes	—

Query parameters

Field	Type	Required	Description
`page`	number	No	Page number (1-indexed). Default `1`, min `1`.
`limit`	number	No	Number of items per page. Default `20`, min `1`, max `100`.

Example request

curl -G https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles \
  -H "Authorization: Bearer sk_live_mer_…" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Example response — 200

{
  "data": [
    {
      "id": "rp_123abc...",
      "merchant_id": "mrc_123",
      "name": "Primary Routing Profile",
      "created_at": "2025-11-20T10:00:00Z",
      "updated_at": "2025-11-21T10:00:00Z",
      "is_active": true,
      "version": 1,
      "payment_method": "*",
      "default_merchant_connector_id": "string"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

POST`/api/v1/merchants/:merchant_id/routing-profiles`

OrgMerchant

Auth: Organization key (with merchant_id) or Merchant key.

Create a routing profile.

Path parameters

Field	Type	Required	Description
`merchant_id`	string	Yes	—

Request fields

Field	Type	Required	Description
`name`	string	Yes	Routing profile name.
`is_active`	boolean	No	Whether the routing profile is active.
`payment_method`	string	No	Payment method scope. * = catch-all. One of `credit_card`, `debit_card`, `pix`, `boleto`, `wallet`, `*`.
`default_merchant_connector_id`	string	Yes	Default connector used when no rule node matches. Cannot be null.

Example request

curl -X POST https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Default Card Profile",
    "is_active": true,
    "payment_method": "*",
    "default_merchant_connector_id": "mc_6d7b9a0e1f2c3d4e5f6a7b8c9d0e1f2a"
  }'

Example response — 201

{
  "id": "rp_123abc...",
  "merchant_id": "mrc_123",
  "name": "Primary Routing Profile",
  "created_at": "2025-11-20T10:00:00Z",
  "updated_at": "2025-11-21T10:00:00Z",
  "is_active": true,
  "version": 1,
  "payment_method": "*",
  "default_merchant_connector_id": "string"
}

DELETE`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id`

OrgMerchant

Auth: Organization key (with merchant_id) or Merchant key.

Delete a routing profile.

Path parameters

Field	Type	Required	Description
`merchant_id`	string	Yes	—
`profile_id`	string	Yes	—

Example request

curl -X DELETE https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c \
  -H "Authorization: Bearer sk_live_mer_…"

Example response — 204 No Content

An empty body is returned on success.

GET`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id`

OrgMerchant

Auth: Organization key (with merchant_id) or Merchant key.

Get a routing profile.

Path parameters

Field	Type	Required	Description
`merchant_id`	string	Yes	—
`profile_id`	string	Yes	—

Example request

curl https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c \
  -H "Authorization: Bearer sk_live_mer_…"

Example response — 200

{
  "id": "rp_123abc...",
  "merchant_id": "mrc_123",
  "name": "Primary Routing Profile",
  "created_at": "2025-11-20T10:00:00Z",
  "updated_at": "2025-11-21T10:00:00Z",
  "is_active": true,
  "version": 1,
  "payment_method": "*",
  "default_merchant_connector_id": "string"
}

PATCH`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id`

OrgMerchant

Auth: Organization key (with merchant_id) or Merchant key.

Update a routing profile.

Path parameters

Field	Type	Required	Description
`merchant_id`	string	Yes	—
`profile_id`	string	Yes	—

Request fields

Field	Type	Required	Description
`name`	string	No	Routing profile name.
`is_active`	boolean	No	Whether the routing profile is active.
`deactivate_conflicting`	boolean	No	Opt in to taking over from the profile that is currently active for this payment method. Only one profile per (merchant, payment_method) may be active, so activating a second one normally returns 409. Send true to deactivate the existing profile and activate this one in a single transaction instead. Ignored when there is no conflict. Requires is_active=true.
`payment_method`	string	No	Payment method scope. * = catch-all. One of `credit_card`, `debit_card`, `pix`, `boleto`, `wallet`, `*`.
`default_merchant_connector_id`	string	No	Default connector used when no rule node matches. Cannot be null.

Example request

curl -X PATCH https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Default Card Profile",
    "is_active": true,
    "deactivate_conflicting": false,
    "payment_method": "*",
    "default_merchant_connector_id": "mc_6d7b9a0e1f2c3d4e5f6a7b8c9d0e1f2a"
  }'

Example response — 200

{
  "id": "rp_123abc...",
  "merchant_id": "mrc_123",
  "name": "Primary Routing Profile",
  "created_at": "2025-11-20T10:00:00Z",
  "updated_at": "2025-11-21T10:00:00Z",
  "is_active": true,
  "version": 1,
  "payment_method": "*",
  "default_merchant_connector_id": "string"
}

PATCH`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/default-connector`

OrgMerchant

Auth: Organization key (with merchant_id) or Merchant key.

The connector used when no routing rule in the profile matches.

Path parameters

Field	Type	Required	Description
`merchant_id`	string	Yes	—
`profile_id`	string	Yes	—

Request fields

Field	Type	Required	Description
`merchant_connector_id`	string	Yes	Merchant connector ID to set as the profile default.

Example request

curl -X PATCH https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c/default-connector \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_connector_id": "mc_6d7b9a0e1f2c3d4e5f6a7b8c9d0e1f2a"
  }'

GET`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes`

OrgMerchant

Auth: Organization key (with merchant_id) or Merchant key.

Every node of the profile’s decision tree, in evaluation order. Returned in the paginated envelope, but unpaginated — one page holds the whole tree.

Path parameters

Field	Type	Required	Description
`merchant_id`	string	Yes	—
`profile_id`	string	Yes	—

Example request

curl https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c/nodes \
  -H "Authorization: Bearer sk_live_mer_…"

Example response — 200

{}

POST`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes`

OrgMerchant

Auth: Organization key (with merchant_id) or Merchant key.

Adds a condition or connector node to the profile’s decision tree.

Path parameters

Field	Type	Required	Description
`merchant_id`	string	Yes	—
`profile_id`	string	Yes	—

Request fields

Field	Type	Required	Description
`node_type`	string	Yes	Node type: condition or action. One of `condition`, `action`.
`parent_node_id`	string \| null	No	Parent node ID. Null for root nodes.
`branch`	string \| null	No	Branch: then or else. Required when parent_node_id is set. One of `then`, `else`.
`position`	number	Yes	Position among siblings (0-based).
`condition_field`	string	No	Field to evaluate. Required for condition nodes. One of `currency`, `amount`, `card_brand`, `bin_country`, `is_recurring`, `math/random`, `installments`.
`condition_operator`	string	No	Comparison operator. Required for condition nodes. One of `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `regex`.
`condition_value`	object	No	Comparison value. Scalar for eq/gt/lt, array for in/not_in, float 0-1 for math/random.
`merchant_connector_id`	string	No	Connector to route to. Required for action nodes.
`require_3ds`	string	No	3DS requirement for this action node. One of `never`, `if_supported`, `always`.
`is_active`	boolean	No	Whether the node is active.

Example request

curl -X POST https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c/nodes \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "node_type": "condition",
    "parent_node_id": "string",
    "branch": "then",
    "position": 0,
    "condition_field": "currency",
    "condition_operator": "eq",
    "condition_value": {},
    "merchant_connector_id": "string",
    "require_3ds": "never",
    "is_active": true
  }'

Example response — 201

{
  "id": "obj_1a2b3c4d",
  "routing_profile_id": "string",
  "parent_node_id": "string",
  "branch": "string",
  "position": 1,
  "node_type": "standard",
  "condition_field": "string",
  "condition_operator": "string",
  "condition_value": {},
  "merchant_connector_id": "string",
  "connector_name": "Acme Store",
  "require_3ds": "string",
  "is_active": true,
  "created_at": "2026-01-15T12:30:00.000Z",
  "updated_at": "2026-01-15T12:30:00.000Z"
}

PATCH`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes/reorder`

OrgMerchant

Auth: Organization key (with merchant_id) or Merchant key.

Sets the evaluation order of the nodes under one parent. Send the complete ordered list of sibling ids for that branch.

Path parameters

Field	Type	Required	Description
`merchant_id`	string	Yes	—
`profile_id`	string	Yes	—

Request fields

Field	Type	Required	Description
`parent_node_id`	string \| null	No	Parent node ID whose children are being reordered. Null for root-level nodes.
`branch`	string \| null	No	Branch of the parent node. Null for root-level nodes. One of `then`, `else`.
`ordered_node_ids`	array	Yes	Ordered list of sibling node IDs in the desired order.

Example request

curl -X PATCH https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c/nodes/reorder \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_node_id": "rrn_6d7b9a0e1f2c3d4e5f6a7b8c9d0e1f2a",
    "branch": "then",
    "ordered_node_ids": [
      "rrn_6d7b9a0e1f2c3d4e5f6a7b8c9d0e1f2a"
    ]
  }'

DELETE`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes/:node_id`

OrgMerchant

Auth: Organization key (with merchant_id) or Merchant key.

Delete a routing tree node.

Path parameters

Field	Type	Required	Description
`merchant_id`	string	Yes	—
`node_id`	string	Yes	—

Example request

curl -X DELETE https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c/nodes/node_2 \
  -H "Authorization: Bearer sk_live_mer_…"

Example response — 204 No Content

An empty body is returned on success.

PATCH`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes/:node_id`

OrgMerchant

Auth: Organization key (with merchant_id) or Merchant key.

Update a routing tree node.

Path parameters

Field	Type	Required	Description
`merchant_id`	string	Yes	—
`node_id`	string	Yes	—

Request fields

Field	Type	Required	Description
`parent_node_id`	string \| null	No	—
`branch`	string \| null	No	One of `then`, `else`.
`position`	number	No	—
`condition_field`	string	No	One of `currency`, `amount`, `card_brand`, `bin_country`, `is_recurring`, `math/random`, `installments`.
`condition_operator`	string	No	One of `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `regex`.
`condition_value`	object	No	—
`merchant_connector_id`	string	No	—
`require_3ds`	string	No	One of `never`, `if_supported`, `always`.
`is_active`	boolean	No	—

Example request

curl -X PATCH https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c/nodes/node_2 \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_node_id": "string",
    "branch": "then",
    "position": 1,
    "condition_field": "currency",
    "condition_operator": "eq",
    "condition_value": {},
    "merchant_connector_id": "string",
    "require_3ds": "never",
    "is_active": true
  }'

Example response — 200

{
  "id": "obj_1a2b3c4d",
  "routing_profile_id": "string",
  "parent_node_id": "string",
  "branch": "string",
  "position": 1,
  "node_type": "standard",
  "condition_field": "string",
  "condition_operator": "string",
  "condition_value": {},
  "merchant_connector_id": "string",
  "connector_name": "Acme Store",
  "require_3ds": "string",
  "is_active": true,
  "created_at": "2026-01-15T12:30:00.000Z",
  "updated_at": "2026-01-15T12:30:00.000Z"
}

Errors

Errors use the standard envelope. The most common cases here:

HTTP	`type`	Typical cause
`400`	`validation_error`	Missing required field, or an operation the current state does not allow.
`401`	`authentication_error`	Missing or invalid API key.
`403`	`authorization_error`	The key lacks the required scope.
`404`	`not_found_error`	The resource does not exist or is not owned by this entity.
`429`	`rate_limit_error`	Rate limit exceeded — back off exponentially.

See Errors for the full catalog.

Routing profiles

The routing profile object

Endpoints

GET/api/v1/merchants/:merchant_id/routing-profiles

POST/api/v1/merchants/:merchant_id/routing-profiles

DELETE/api/v1/merchants/:merchant_id/routing-profiles/:profile_id

GET/api/v1/merchants/:merchant_id/routing-profiles/:profile_id

PATCH/api/v1/merchants/:merchant_id/routing-profiles/:profile_id

PATCH/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/default-connector

GET/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes

POST/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes

PATCH/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes/reorder

DELETE/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes/:node_id

PATCH/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes/:node_id

Errors

Related

On this page

GET`/api/v1/merchants/:merchant_id/routing-profiles`

POST`/api/v1/merchants/:merchant_id/routing-profiles`

DELETE`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id`

GET`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id`

PATCH`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id`

PATCH`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/default-connector`

GET`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes`

POST`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes`

PATCH`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes/reorder`

DELETE`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes/:node_id`

PATCH`/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes/:node_id`