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

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.