Merchant routing

Configure a merchant's smart-routing rules from the Dashboard — routing profiles, their ordered nodes, the default connector, and node reordering.

These endpoints back the Dashboard's routing screen. A routing profile holds an ordered list of nodes that decide which connector attempts each charge; the order is also the fallback chain that powers cascade. When no node matches, the profile's default connector takes the charge.

Reordering nodes changes live routing for the next transaction, so it is the highest-leverage — and most sensitive — control here. Confirm the effect on a transaction's timeline, which records the node that produced each attempt.

These endpoints power the Tokeflow Dashboard UI. They are session-authenticated (JWT bearer) — the token comes from signing in to the Dashboard, not from an sk_/pk_ API key. Requests also carry the x-merchant-id header identifying the merchant in context, and the signed-in user must be a member with access to it.

The routing profile object

Returned by the list and retrieve endpoints on this page.

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/merchant/routing/profiles`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

List routing profiles.

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/merchant/routing/profiles \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

POST`/api/v1/merchant/routing/profiles`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

Create routing profile.

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/merchant/routing/profiles \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -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/merchant/routing/profiles/:id`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

Delete routing profile.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	—

Example request

curl -X DELETE https://api.tokeflow.com/api/v1/merchant/routing/profiles/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

GET`/api/v1/merchant/routing/profiles/:id`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

Get routing profile with rules.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	—

Example request

curl https://api.tokeflow.com/api/v1/merchant/routing/profiles/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

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/merchant/routing/profiles/:id`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

Update routing profile.

Path parameters

Field	Type	Required	Description
`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/merchant/routing/profiles/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -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"
}

GET`/api/v1/merchant/routing/profiles/:id/rules`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

Get routing tree for profile.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	—

Example request

curl https://api.tokeflow.com/api/v1/merchant/routing/profiles/obj_1a2b3c4d/rules \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

POST`/api/v1/merchant/routing/profiles/:id/rules`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

Create routing rule.

Path parameters

Field	Type	Required	Description
`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/merchant/routing/profiles/obj_1a2b3c4d/rules \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -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"
}

DELETE`/api/v1/merchant/routing/rules/:ruleId`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

Delete routing rule.

Path parameters

Field	Type	Required	Description
`ruleId`	string	Yes	—

Example request

curl -X DELETE https://api.tokeflow.com/api/v1/merchant/routing/rules/123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

PATCH`/api/v1/merchant/routing/rules/:ruleId`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

Update routing rule.

Path parameters

Field	Type	Required	Description
`ruleId`	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/merchant/routing/rules/123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -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	Meaning
`400`	Invalid parameters or a state that does not allow this operation.
`401`	Missing, expired, or invalid Dashboard session token.
`403`	Authenticated, but the signed-in user lacks access to this entity.
`404`	The record does not exist or is not visible to this entity.

Merchant routing

The routing profile object

Endpoints

GET/api/v1/merchant/routing/profiles

POST/api/v1/merchant/routing/profiles

DELETE/api/v1/merchant/routing/profiles/:id

GET/api/v1/merchant/routing/profiles/:id

PATCH/api/v1/merchant/routing/profiles/:id

GET/api/v1/merchant/routing/profiles/:id/rules

POST/api/v1/merchant/routing/profiles/:id/rules

DELETE/api/v1/merchant/routing/rules/:ruleId

PATCH/api/v1/merchant/routing/rules/:ruleId

Errors

Related

On this page

GET`/api/v1/merchant/routing/profiles`

POST`/api/v1/merchant/routing/profiles`

DELETE`/api/v1/merchant/routing/profiles/:id`

GET`/api/v1/merchant/routing/profiles/:id`

PATCH`/api/v1/merchant/routing/profiles/:id`

GET`/api/v1/merchant/routing/profiles/:id/rules`

POST`/api/v1/merchant/routing/profiles/:id/rules`

DELETE`/api/v1/merchant/routing/rules/:ruleId`

PATCH`/api/v1/merchant/routing/rules/:ruleId`