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

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 passed on the checkout session takes priority, then the account’s default route. 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:

1
{
2
  "id": "proute_xyz789",
3
  "name": "US Optimized",
4
  "description": "Primary route for US customers",
5
  "processors": [
6
    { "processor_id": "proc_abc123" },
7
    { "processor_id": "proc_def456" },
8
    { "processor_id": "proc_ghi789" }
9
  ],
10
  "created_at": "2024-01-15T10:30:00Z",
11
  "updated_at": "2024-01-15T10:30:00Z"
12
}

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.

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

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

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_..."

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:

1
{
2
  "items": [
3
    {
4
      "id": "ral_abc123",
5
      "route_id": "proute_xyz789",
6
      "action": "updated",
7
      "operator_identity": "casey@example.com",
8
      "details": {
9
        "changes": {
10
          "processors": {
11
            "old_value": [{ "processor_id": "proc_abc123" }],
12
            "new_value": [
13
              { "processor_id": "proc_def456" },
14
              { "processor_id": "proc_abc123" }
15
            ]
16
          }
17
        }
18
      },
19
      "reason": null,
20
      "created_at": "2026-02-01T15:30:00Z"
21
    },
22
    {
23
      "id": "ral_def456",
24
      "route_id": "proute_xyz789",
25
      "action": "created",
26
      "operator_identity": "api_key_tok_abc123",
27
      "details": {
28
        "name": "US Optimized",
29
        "description": null,
30
        "processors": [{ "processor_id": "proc_abc123" }]
31
      },
32
      "reason": null,
33
      "created_at": "2026-01-15T10:30:00Z"
34
    }
35
  ],
36
  "total": 2,
37
  "has_more": false
38
}

Audit log fields:

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:

1
{
2
  "cascading_enabled": true,
3
  "fallback_processor_1_id": "proc_abc123",
4
  "fallback_processor_2_id": "proc_def456",
5
  "update_default_pm_on_fallback": false,
6
  "max_fallback_payment_methods": 1
7
}

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:

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