● 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.

Get the current rule set

GET /v1/routing/rules

Returns the complete rule set with its version. Keep it in your repository, edit it, and push it back through the publish endpoint — that way routing changes get code review and a rollback path.

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
Request
curl -X GET https://api.baton.example/v1/routing/rules \
  -H "Authorization: Bearer sk_live_xxx"
Response · 200
{
  "version": 7,
  "published_at": "2026-11-14T06:20:00Z",
  "published_by": "[email protected]",
  "rules": [
    {
      "name": "EU cards",
      "priority": 10,
      "conditions": {
        "country": [
          "DE",
          "FR"
        ],
        "currency": [
          "EUR"
        ]
      },
      "targets": [
        {
          "connector_code": "adyen",
          "weight": 100
        },
        {
          "connector_code": "stripe"
        }
      ],
      "three_ds": "auto"
    }
  ]
}

Simulate routing

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"
  ]
}

Publish a rule set

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

400Invalid parameters
409The 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=..."