Skip to navigation

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.

View as Markdown

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.

Success Failed Success Failed Success Failed Customer submits payment Processor 1: Stripe Payment complete Processor 2: Authorize.net Processor 3: Airwallex Payment failed

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

curl -X POST https://app.paymentkit.com/api/{account_id}/processor-routes \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "US Optimized",
"description": "Primary route for US customers",
"processors": [
{ "processor_id": "proc_abc123" },
{ "processor_id": "proc_def456" },
{ "processor_id": "proc_ghi789" }
]
}'

name and a non-empty processors list are required; description is optional.

Response:

{
"id": "proute_xyz789",
"name": "US Optimized",
"description": "Primary route for US customers",
"processors": [
{ "processor_id": "proc_abc123" },
{ "processor_id": "proc_def456" },
{ "processor_id": "proc_ghi789" }
],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}

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:

curl -X POST https://app.paymentkit.com/api/{account_id}/checkout-sessions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "cus_abc123",
"line_items": [
{ "price_id": "price_xyz", "quantity": 1 }
],
"processor_route_id": "proute_xyz789",
"success_url": "https://example.com/success",
"return_url": "https://example.com/return"
}'

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.

curl -X POST https://app.paymentkit.com/api/{account_id}/processor-routes \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Visa in EUR to Adyen",
"match_mode": "all",
"conditions": [
{ "field": "card_brand", "operator": "equals", "value": "visa" },
{ "field": "currency", "operator": "equals", "value": "EUR" }
],
"routes": [ { "route_id": "proute_adyen123" } ],
"position": 1,
"status": "active"
}'
  • GET /api/{account_id}/processor-routes/matchers lists every condition field, its operators and its values.
  • match_mode is all (every condition must match) or any (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.
  • type is fixed at creation. A route cannot be returned to draft; retire it with DELETE (it becomes inactive and 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:

curl -X POST https://app.paymentkit.com/api/{account_id}/processor-routes/reorder \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "route_ids": ["proute_rule2", "proute_rule1"] }'

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.

curl -X POST https://app.paymentkit.com/api/{account_id}/payment-links \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Spring sale",
"mode": "payment",
"line_items": [ { "price_id": "price_xyz", "quantity": 1 } ],
"processor_route_id": "proute_rule1",
"success_url": "https://example.com/success"
}'

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:

fallback_reasonWhen
route_not_foundNo route of your account has that id.
route_inactiveThe route is not active.
route_stops_every_paymentThe route stops every payment.
route_cannot_charge_cardSubscriptions: the first charge could not go through the route with the customer’s payment methods. Also returned by POST /invoices/{id}/collect when that collect would charge none of its cards through the invoice’s route.
"routing": {
"requested_route_id": "proute_xyz789",
"applied_route_id": null,
"fallback_reason": "route_inactive",
"fallback_detail": "Route 'proute_xyz789' is inactive; only active routes can be pinned",
"charge_route_id": null,
"charge_route_decision_source": null
}

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.

curl -X PATCH https://app.paymentkit.com/api/accounts/{account_id}/default-processor-route \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "default_processor_route_id": "proute_xyz789" }'

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

{
"external_id": "pa_001",
"credential_source": "network_token",
"fallback_reason": null,
"cryptogram_generated_at": "2026-08-18T15:33:58.100000Z"
}
{
"external_id": "pa_002",
"credential_source": "pan",
"fallback_reason": "soft_decline_token_error",
"cryptogram_generated_at": null
}

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:

fallback_reasonMeaning
no_tokenNo network token was available to attempt
token_inactiveThe network token exists but isn’t active
timeout_fallbackGenerating the token’s cryptogram timed out
processor_unsupportedThe processor doesn’t support network tokens
status_check_failedCouldn’t confirm the token’s status
cryptogram_unavailableNo cryptogram was available for the token
sandbox_unsupportedNetwork tokens aren’t supported in sandbox
byot_not_enabledThe processor account isn’t set up to accept network tokens from PaymentKit
no_network_referenceA recurring (merchant-initiated) charge needs the network’s prior transaction ID to use a network token. None could be found, so the token wasn’t charged

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

FieldValuesDescription
credential_sourcenetwork_token, pan, nullWhich credential the attempt charged with. null on non-card payment methods (wallets, bank debits, etc.)
fallback_reasonone of the 10 values above, or nullSet when the attempt is a fallback; null on a normal network-token or non-fallback PAN attempt
cryptogram_generated_atRFC 3339 timestamp, or nullWhen the network-token cryptogram was generated. Only set on network_token attempts

Two invariants hold on every attempt:

  • fallback_reason is only ever non-null when credential_source is pan.
  • cryptogram_generated_at is only ever non-null when credential_source is network_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 attempt
  • GET /api/{account_id}/payments/processor_attempts/ — list, filterable by credential_source and fallback_reason
  • GET /api/{account_id}/payments/processor_attempts/by_intent/{payment_intent_external_id} — all attempts for a payment intent

Manage routes

List all routes:

curl https://app.paymentkit.com/api/{account_id}/processor-routes \
-H "Authorization: Bearer sk_live_..."

Update a route:

curl -X PATCH https://app.paymentkit.com/api/{account_id}/processor-routes/proute_xyz789 \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "US Optimized v2",
"processors": [
{ "processor_id": "proc_def456" },
{ "processor_id": "proc_abc123" }
]
}'

Delete a route:

curl -X DELETE https://app.paymentkit.com/api/{account_id}/processor-routes/proute_xyz789 \
-H "Authorization: Bearer sk_live_..."

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.

curl https://app.paymentkit.com/api/{account_id}/processor-routes/proute_xyz789/audit-log \
-H "Authorization: Bearer sk_live_..."

Response:

{
"items": [
{
"id": "ral_abc123",
"route_id": "proute_xyz789",
"action": "updated",
"operator_identity": "casey@example.com",
"details": {
"changes": {
"processors": {
"old_value": [{ "processor_id": "proc_abc123" }],
"new_value": [
{ "processor_id": "proc_def456" },
{ "processor_id": "proc_abc123" }
]
}
}
},
"reason": null,
"created_at": "2026-02-01T15:30:00Z"
},
{
"id": "ral_def456",
"route_id": "proute_xyz789",
"action": "created",
"operator_identity": "api_key_tok_abc123",
"details": {
"name": "US Optimized",
"description": null,
"processors": [{ "processor_id": "proc_abc123" }]
},
"reason": null,
"created_at": "2026-01-15T10:30:00Z"
}
],
"total": 2,
"has_more": false
}

Audit log fields:

FieldDescription
actioncreated, updated, or deleted
operator_identityWho made the change — a user’s email (e.g. casey@example.com) or an API-key subject (api_key_<token_id>)
detailsFor updated, a changes map of { field: { old_value, new_value } }; for created/deleted, the full route config (name, description, processors)
reasonOptional reason for the change (null when none was provided)
created_atWhen the change occurred

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

curl https://app.paymentkit.com/api/accounts/{account_id}/mit-settings \
-H "Authorization: Bearer sk_live_..."

Response:

{
"cascading_enabled": true,
"fallback_processor_1_id": "proc_abc123",
"fallback_processor_2_id": "proc_def456",
"update_default_pm_on_fallback": false,
"max_fallback_payment_methods": 1
}

Update MIT settings

curl -X PATCH https://app.paymentkit.com/api/accounts/{account_id}/mit-settings \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"cascading_enabled": true,
"fallback_processor_1_id": "proc_abc123",
"fallback_processor_2_id": "proc_def456"
}'

Settings fields:

FieldTypeDescription
cascading_enabledbooleanEnable fallback to other processors when the last successful one is unavailable (default: false)
fallback_processor_1_idstringFirst fallback processor ID
fallback_processor_2_idstringSecond fallback processor ID
update_default_pm_on_fallbackbooleanWhen true, a successful fallback card re-pins the subscription and invoice default payment method to that card (default: false)
max_fallback_payment_methodsintegerMaximum number of fallback cards to try after the primary default card, 0–10 (0 = primary only, default: 1)

How MIT cascade works:

  1. PaymentKit attempts payment with the subscription’s last successful processor
  2. If that fails and cascading_enabled is true, it tries fallback_processor_1_id
  3. If that also fails, it tries fallback_processor_2_id
  4. 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.