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:

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

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

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.

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 (single attempt, no retry)

The remaining fallback_reason values are resolved before any charge is attempted. In these cases the network token is never charged at all, so the payment shows a single pan attempt, not a pair:

If you see one of these on a payment’s single pan attempt, PaymentKit charged the card number directly. There is no preceding network-token attempt to reconcile against.

Fields on a processor attempt

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

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:

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:

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