Payment Orchestration

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 /v1/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.

Without a defined route, PaymentKit will first try your default processor, and then fall back to other connected processors by connection order.

Create a route

$curl -X POST https://api.paymentkit.com/v1/processor-routes \
>  -H "Authorization: Bearer sk_live_..." \
>  -H "Content-Type: application/json" \
>  -d '{
>    "name": "US Optimized",
>    "processors": [
>      { "processor_id": "proc_abc123" },
>      { "processor_id": "proc_def456" },
>      { "processor_id": "proc_ghi789" }
>    ]
>  }'

Response:

${
>  "id": "proute_xyz789",
>  "name": "US Optimized",
>  "processors": [
>    { "processor_id": "proc_abc123" },
>    { "processor_id": "proc_def456" },
>    { "processor_id": "proc_ghi789" }
>  ],
>  "created_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 /v1/processor-routes. For cascade pricing, each tier 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://api.paymentkit.com/v1/checkout/sessions \
>  -H "Authorization: Bearer sk_live_..." \
>  -d customer_id="cus_abc123" \
>  -d line_items[0][price_id]="price_xyz" \
>  -d line_items[0][quantity]=1 \
>  -d processor_route_id="proute_xyz789" \
>  -d success_url="https://example.com/success"

Set a default route (optional)

Apply a route to all checkout sessions without needing to specify it each time.

$curl -X PATCH https://api.paymentkit.com/v1/accounts/acc_xxx \
>  -H "Authorization: Bearer sk_live_..." \
>  -d default_processor_route_id="proute_xyz789"

Manage routes

List all routes:

$curl https://api.paymentkit.com/v1/processor-routes \
>  -H "Authorization: Bearer sk_live_..."

Update a route:

$curl -X PATCH https://api.paymentkit.com/v1/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://api.paymentkit.com/v1/processor-routes/proute_xyz789 \
>  -H "Authorization: Bearer sk_live_..."

Routes currently referenced by checkout sessions or set as account default cannot be deleted.

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://api.paymentkit.com/v1/processor-routes/proute_xyz789/audit-log \
>  -H "Authorization: Bearer sk_live_..."

Response:

1{
2  "items": [
3    {
4      "id": "ral_abc123",
5      "route_id": "proute_xyz789",
6      "action": "updated",
7      "operator_identity": "user:usr_abc123",
8      "details": {
9        "before": { "processors": ["proc_abc123"] },
10        "after": { "processors": ["proc_def456", "proc_abc123"] }
11      },
12      "created_at": "2026-02-01T15:30:00Z"
13    },
14    {
15      "id": "ral_def456",
16      "route_id": "proute_xyz789",
17      "action": "created",
18      "operator_identity": "api_key:sk_live_xxx",
19      "details": {
20        "name": "US Optimized",
21        "processors": ["proc_abc123"]
22      },
23      "created_at": "2026-01-15T10:30:00Z"
24    }
25  ],
26  "total": 2,
27  "limit": 50,
28  "offset": 0
29}

Audit log fields:

FieldDescription
actioncreated, updated, or deleted
operator_identityWho made the change (user:usr_xxx, api_key:sk_xxx)
detailsBefore/after values for updates, or full config for create/delete
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://api.paymentkit.com/api/{account_id}/mit-settings \
>  -H "Authorization: Bearer sk_live_..."

Response:

1{
2  "cascading_enabled": true,
3  "fallback_processor_1_id": "proc_abc123",
4  "fallback_processor_2_id": "proc_def456"
5}

Update MIT settings

$curl -X PATCH https://api.paymentkit.com/api/{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 primary fails (default: false)
fallback_processor_1_idstringFirst fallback processor ID
fallback_processor_2_idstringSecond fallback processor ID

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.