***

title: Routing payments
subtitle: >-
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 **Developers > Payment Processors** or via `GET /v1/processors`).

<Callout intent="info">
  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.**
</Callout>

***

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

```mermaid
flowchart TD
    A[Customer submits payment] --> B[Processor 1: Stripe]
    B -->|Success| C[Payment complete]
    B -->|Failed| D[Processor 2: Authorize]
    D -->|Success| C
    D -->|Failed| E[Processor 3: Airwallex]
    E -->|Success| C
    E -->|Failed| F[Payment failed]

```

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

```bash
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:

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

<Callout intent="info">
  **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.
</Callout>

Pass the `processor_route_id` when creating a checkout session:

```bash
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.

```bash
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:

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

Update a route:

```bash
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:

```bash
curl -X DELETE https://api.paymentkit.com/v1/processor-routes/proute_xyz789 \
  -H "Authorization: Bearer sk_live_..."
```

<Warning>
  Routes currently referenced by **checkout sessions** or set as **account default** cannot be deleted.
</Warning>