guides

Routing & fallback

Rules are evaluated in priority order (lower number first); the first matching rule supplies an ordered PSP chain — primary first, fallbacks after. With no matching rule, every eligible enabled connection is used in the order it was added.

Creating rules

POST /v1/routing_rules
{
  "name": "EUR cards → Adyen first",
  "priority": 10,
  "conditions": {
    "payment_method_types": ["card"],
    "currencies": ["EUR"],
    "amount_gte": 1000
  },
  "psp_order": ["psp_adyen…", "psp_stripe…"]
}

Conditions are ANDed; absent fields match anything. Manage rules from the dashboard's rule builder or via GET / PATCH / DELETE /v1/routing_rules.

Fallback semantics

Falls back: retryable technical failures — PSP timeouts, unreachable or misconfigured providers, PSP 5xx. The next connection in the chain is tried with a fresh attempt.
Never falls back: declines. insufficient_funds from one PSP means the issuer said no — retrying it elsewhere invites fraud flags and duplicate charges.
Skipped up front: disabled connections (manual kill switch) and connections whose health checks are failing.

Explainability

Every attempt records its routing decision — strategy, matched rule id, position in the chain, and a fallback flag. You'll find it in API responses under attempts[].routing and visually on the payment timeline in the dashboard.

"attempts": [
  { "provider": "adyen",  "status": "failed",   "error_code": "psp_timeout" },
  { "provider": "stripe", "status": "captured", "routing": { "fallback": true } }
]