● Routing · /v1 Routing
Routing rules as configuration-as-code: published from your repository, versioned, and simulated before release. We do not lock orchestration inside the console.
POST /v1/routing/simulate
A dry run that creates no payment. It answers "which provider would this take, and why".
explain gives the hit and miss reason for every rule — this is the only way to explain why a payment did not take the route you expected.
Wire it into CI: assert a set of cases before rules are merged, which beats discovering a drop in auth rate after release.
Body
amountrequired | integer | |
currencyrequired | string | |
country | string | |
payment_method_type | string | |
card_bin | string | |
rules | object | |
└versionrequired | integer | Rule set version. Publishing must carry the current version; a mismatch returns 409 so two people cannot overwrite each other |
└rulesrequired | object[] | |
└namerequired | string | |
└priority | integer | Lower numbers match first. Within the same priority, array order wins |
└conditionsrequired | object | Match conditions; see the routing fields page in the console for valid values. Every condition must hold for the rule to match |
└targetsrequired | object[] | Cascaded in order. The first is preferred, the rest are backups used after a soft decline |
└three_ds | auto | force | skip | |
└published_atrequired | string<date-time> | |
└published_by | string | |
Response 200
matched_rule | string | The name of the matched rule; null means the default route |
targets | string[] | Cascade order |
three_ds | string | |
explain | string[] | Per-rule hit and miss reasons — this is how you explain why a payment did not take the route you expected |
Request
curl -X POST https://api.baton.example/v1/routing/simulate \
-H "Authorization: Bearer sk_live_xxx" \
-H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
-H "Content-Type: application/json" \
-d '{
"amount": 8900,
"currency": "EUR",
"country": "DE",
"payment_method_type": "card",
"card_bin": "411111"
}' Response · 200
{
"matched_rule": "EU cards",
"targets": [
"adyen",
"stripe"
],
"three_ds": "auto",
"explain": [
"rule \"EU cards\" matched: country in [DE,FR] and currency in [EUR]",
"rule \"High value\" skipped: amount 8900 < 50000"
]
} POST /v1/routing/rules/publish
The whole set is replaced; there is no partial merge, because merging routing rules produces combinations nobody intended.
The current version is mandatory: a mismatch returns 409 so two people cannot overwrite each other.
Simulate before you publish; publishing straight to live has no safety net.
Headers
Idempotency-Keyrequired | string | A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment. |
Body
versionrequired | integer | Rule set version. Publishing must carry the current version; a mismatch returns 409 so two people cannot overwrite each other |
rulesrequired | object[] | |
└namerequired | string | |
└priority | integer | Lower numbers match first. Within the same priority, array order wins |
└conditionsrequired | object | Match conditions; see the routing fields page in the console for valid values. Every condition must hold for the rule to match |
└targetsrequired | object[] | Cascaded in order. The first is preferred, the rest are backups used after a soft decline |
└connector_code | string | |
└weight | integer | Weight for splitting traffic between targets at the same level, used for pilots |
└three_ds | auto | force | skip | |
published_atrequired | string<date-time> | |
published_by | string | |
Response 200
version | integer | Rule set version. Publishing must carry the current version; a mismatch returns 409 so two people cannot overwrite each other |
rules | object[] | |
└name | string | |
└priority | integer | Lower numbers match first. Within the same priority, array order wins |
└conditions | object | Match conditions; see the routing fields page in the console for valid values. Every condition must hold for the rule to match |
└targets | object[] | Cascaded in order. The first is preferred, the rest are backups used after a soft decline |
└connector_code | string | |
└weight | integer | Weight for splitting traffic between targets at the same level, used for pilots |
└three_ds | auto | force | skip | |
published_at | string<date-time> | |
published_by | string | |
Errors
| 400 | Invalid parameters |
| 409 | The idempotency key was reused with a different body, or the object's state does not allow this operation |
Request
curl -X POST https://api.baton.example/v1/routing/rules/publish \
-H "Authorization: Bearer sk_live_xxx" \
-H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
-H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."