Routing payments
Define processor routes—ordered lists of payment processors—to control how payments are attempted. When a customer pays, PaymentKit tries each processor in order until one succeeds.
Before you begin
Make sure you have:
- At least two connected payment processors.
- Processor IDs handy (find them in Orchestration > Payment processors or via
GET /api/{account_id}/payments/processors).
If you only have one processor connected, PaymentKit will only use your default processor. At this time, payment routes can only be defined via the API.
How payment routes work
PaymentKit will try each processor in the order of your defined route until one succeeds. If a processor is unavailable or doesn’t support the currency, PaymentKit skips to the next processor automatically.
Routes are resolved in precedence order: a route named on the checkout session (or on the payment link it was opened from) takes priority, then a route pinned to the payment, then your account’s routing rules in their evaluation order, then the account’s default route. For an invoice charge made outside checkout (a subscription’s first charge or renewal, a dunning retry, POST /invoices/{id}/collect), the more specific route wins: the invoice’s own route, then the route pinned to its subscription, then your routing rules, then the default route. A route that does not apply falls to the next one. If no route is configured, PaymentKit uses your default processor.
Create a route
name and a non-empty processors list are required; description is optional.
Response:
Use a route in checkout
Pass a single processor_route_id when creating a checkout session. The route itself contains an ordered list of processors — PaymentKit tries each one sequentially until a payment succeeds. You don’t pass multiple processor IDs directly; instead, define the processor list inside the route and reference the route by its ID.
One route ID, multiple processors. The processor_route_id field accepts a single route ID (e.g., proute_xyz789), not an array of processor IDs. To control which processors are used and in what order, configure them within the route via POST /api/{account_id}/processor-routes. For cascade pricing, each tier (cascade_line_items[]) can specify its own processor_route_id to use a different fallback chain.
Pass the processor_route_id when creating a checkout session:
Routing rules: routes with conditions
A route may carry conditions — facts about the payment it applies to — and a position in your account’s evaluation order. Such a route is a routing rule: on every card charge, PaymentKit walks the positioned routes from position 1 down and the first one whose conditions match decides the processors. A route with no position is never evaluated on its own; it only runs when a checkout session, a payment link, a pin, another route or the account default names it.
A route’s steps may also be other routes of your account (routes instead of processors): a standard_cascade over routes tries each in turn and skips a route that does not apply, a weighted route over routes splits traffic by percentage, and a stop route halts the payment when its conditions match.
GET /api/{account_id}/processor-routes/matcherslists every conditionfield, its operators and its values.match_modeisall(every condition must match) orany(one is enough).- A positioned route needs at least one condition. A route with no conditions always applies, which is right for a plain route but would shadow every rule after it in the evaluation order; use the account default route for catch-all behaviour.
- Card facts (
card_brand,card_bin,card_funding_type,card_issuer_country) are read for a first charge as well as for a saved card, so a rule on them steers a new customer’s first payment. typeis fixed at creation. A route cannot be returned todraft; retire it withDELETE(it becomesinactiveand leaves the evaluation order).
Reorder the whole evaluation order in one call. The list must name every positioned route that is not retired; a route not yet in the order may be listed to add it, and PATCH with "position": null removes one:
A route on a checkout session or a payment link
processor_route_id on a checkout session may name any active route of your account, a routing rule included: its conditions are evaluated for that session, and if they do not match the session falls through to your account’s routing. Instead of an id you can send an inline_route — a one-off definition in the same shape as a stored route (type, conditions, match_mode, processors or routes) that is not saved as a resource. The two are mutually exclusive.
A payment link takes the same two fields. Every checkout opened from the link is created with the link’s route. A route retired after the link was saved is dropped at open time rather than failing the open, and that checkout runs your account’s routing instead.
A route on a subscription or an invoice
Send processor_route_id on POST /api/{account_id}/subscriptions to pin a route to the new subscription. The pin is stored before the first charge, so the first charge, renewals and dunning retries all go through it. Change it later with POST /api/{account_id}/subscriptions/{id}/route, or remove it with DELETE /api/{account_id}/subscriptions/{id}/route.
Send processor_route_id on POST /api/{account_id}/invoices to pin a route to one invoice. While the route applies, the invoice’s card charges go through it (POST /invoices/{id}/collect, a payment from the customer portal, dunning retries), ahead of its subscription’s pin; if it stops applying (for example, it is retired), they fall to the subscription’s pin, then your routing rules. Each collection of the invoice checks the route against the cards it would try, in order: if it would charge none of them through the route (for example, none is saved on a processor the route names, or a card it reaches first cannot be charged at all under the route), the route does not apply to that collection, which routes as if the invoice had no route, and the POST /invoices/{id}/collect response’s routing object gives fallback_reason route_cannot_charge_card. If it would reach a card the route can charge, the route applies. It can be set only when the invoice is created.
Both pins apply to card payment methods while your account’s routing engine is enabled. Dashboard users need the routing_rule:edit permission to set one; API keys always may.
A route that cannot be used is not pinned, and the subscription or invoice is still created. Its charges route as if no route had been named, and the response’s routing object says why:
When the route is pinned, applied_route_id repeats it and fallback_reason is null. charge_route_id and charge_route_decision_source show the route the charge made in that request went through; they are null when nothing was charged or the routing engine is off.
Set a default route (optional)
Apply a route to all checkout sessions without needing to specify it each time. Set default_processor_route_id to null to clear the default.
Token fallback retries (CIT)
When a customer pays with a network token and the charge is declined, PaymentKit can automatically retry the payment once using the card number instead of the token, on the same processor. This section covers that retry, how to tell it apart from a duplicate charge, and the other reasons a payment might fall back from a network token to a card number without a visible retry.
This section covers checkout (CIT) payments.
The retry: soft_decline_token_error
If a network-token charge is declined for a reason unrelated to the card itself, for example a processor-side issue reading the token, PaymentKit retries immediately with the underlying card number. The card itself is usually fine; only the token attempt failed.
- One retry, with the card number, on the same processor as the original attempt.
- One retry per processor, per payment.
- Declines that indicate a problem with the card itself never trigger this retry: lost or stolen card, pick-up card, expired card, incorrect CVC, and unsupported card. Retrying these with the same card would not change the outcome.
This is the only fallback reason that produces two attempts on a payment, one network_token attempt followed by one pan attempt. Seeing both is expected, not a duplicate charge.
This retry is currently supported on a subset of processors. Coverage may expand over time; reach out to support if you need to confirm whether it’s active for a specific processor on your route.
Example: a fallback pair
The first attempt is the original network-token charge. The second is the fallback retry, identified by fallback_reason: soft_decline_token_error. Only one of the two can succeed and result in a captured payment.
If you use processor cascading, a payment can show this same two-attempt pair on each processor the route tries, not just once overall. A cascaded payment that falls back on every processor it attempts is still one customer charge, not one charge per attempt shown.
Other fallback reasons (no network-token charge)
The remaining fallback_reason values are resolved before any charge is attempted. In these cases the network token is never charged at all, so there is no network_token and pan pair:
If you see one of these on a pan attempt, the network token was never charged. There is no preceding network-token attempt to reconcile against. On a checkout (CIT) payment, that pan attempt is the charge. On a recurring (MIT) payment, the row is a record only: nothing was sent to that processor.
Fields on a processor attempt
Two invariants hold on every attempt:
fallback_reasonis only ever non-null whencredential_sourceispan.cryptogram_generated_atis only ever non-null whencredential_sourceisnetwork_token.
Where to find this
Both attempts are visible on the payment’s detail page in the dashboard, and via the processor attempts API:
GET /api/{account_id}/payments/processor_attempts/{external_id}— a single attemptGET /api/{account_id}/payments/processor_attempts/— list, filterable bycredential_sourceandfallback_reasonGET /api/{account_id}/payments/processor_attempts/by_intent/{payment_intent_external_id}— all attempts for a payment intent
Manage routes
List all routes:
Update a route:
Delete a route:
Deleting a route retires it: it becomes inactive, leaves the evaluation order, and is skipped by any checkout session, payment link or cascade tier that still names it. A route cannot be retired while an active route points at it or while it is the account default; those attempts return 409 Conflict.
View route audit log
Track changes to a processor route over time. The audit log records who made changes, what changed, and when.
Response:
Audit log fields:
Audit logs are retained even after a route is deleted. Query by route external ID to see historical changes.
MIT cascade settings
Control how recurring/subscription payments (Merchant Initiated Transactions) retry across processors when the last successful processor is unavailable.
By default, MITs use only the subscription’s last successful processor. Enable cascade to try fallback processors in order when the primary fails.
Get MIT settings
Response:
Update MIT settings
Settings fields:
How MIT cascade works:
- PaymentKit attempts payment with the subscription’s last successful processor
- If that fails and
cascading_enabledistrue, it triesfallback_processor_1_id - If that also fails, it tries
fallback_processor_2_id - After any success, that processor becomes the new “last successful” for future MITs
Use MIT cascading for high-value recurring payments where maximizing collection success outweighs the cost of multiple processor attempts.