Configure processor routing
Beta

Last updated: July 9, 2025

You can set custom routing and retry strategies using the Payments API to control the flow of your payments at an API level. This enables you to:

Be more flexible with how you route payments.
Quickly iterate on your payment routing and retry strategies.
Leverage your own tools to set routing rules – For example, using A/B testing.

For example, you may want to route a payment through a specific processor if:

Your business type qualifies for reduced scheme fees from a specific processor.
The value of the transaction means it's cheaper to use a processor that charges a fixed fee instead of a percentage-based fee, or vice versa.

Information

To enable custom payment routing, contact your account manager or request support.

Check which processors are available on your account before you set which processors to route your payment through.

To return the processors available for a specific processing channel, pass the processing_channel_id as a query parameter. For example:


1https://api.checkout.com/payment-methods?processing_channel_id=pc_ovo75iz4hdyudnx6tu74mum3fq

get

https://api.checkout.com/payment-methods


1{
2  "methods": [
3    {
4      "type": "star"
5    },
6    {
7      "type": "nyce"
8    },
9    {
10      "type": "maestro"
11    }
12  ]
13}

To set your payment routing rules, call the Request a payment endpoint, and provide the routing.attempts array. Each object in the array must be a unique expression of a processor rule.

You can set each attempts.scheme value to one of the following:

Scheme	Value
Accel	`accel`
American Express	`amex`
Cartes Bancaires	`cartes_bancaires`
Diners Club International	`diners`
Discover	`discover`
JCB	`jcb`
Mada	`mada`
Maestro	`maestro`
Mastercard	`mastercard`
NYCE	`nyce`
OmanNet	`omannet`
Pulse	`pulse`
STAR	`star`
UnionPay International	`upi`
Visa	`visa`

Information

We only attempt an authorization with the processors you explicitly include in your request.

We attempt to route the payment authorization to the processors you specify, in the order you set. If an attempt is declined or the card is not eligible to be processed with the specified processor, we attempt authorization with the next processor.

For example, in the following request:

We attempt to send the authorization to the star processor first.
If star declines the attempt, we immediately send the authorization to the nyce processor.
If nyce accepts the authorization, we do not attempt to authorize with maestro.

post

https://api.checkout.com/payments


1{
2  "source": {
3    "type": "card",
4    "number": "4242424242424242",
5    "expiry_month": 12,
6    "expiry_year": 2022
7  },
8  "amount": 6500,
9  "currency": "USD",
10  "processing_channel_id": "pc_ovo75iz4hdyudnx6tu74mum3fq",
11  "routing": {
12    "attempts": [
13      { 
14        "scheme": "star"
15      }, 
16      { 
17        "scheme": "nyce"
18      }, 
19      {
20        "scheme": "maestro"
21      }
22    ]
23  },
24  "reference": "ORD-5023-4E89",
25  "success_url": "https://example.com/payments/success",
26  "failure_url": "https://example.com/payments/fail"
27}


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "action_id": "act_mbabizu24mvu3mela5njyhpit4",
4  "amount": 6500,
5  "currency": "USD",
6  "approved": true,
7  "status": "Authorized",
8  "auth_code": "770687",
9  "response_code": "10000",
10  "response_summary": "Approved",
11  "processing": {
12    "scheme": "nyce"
13  },
14  "source": {
15    "type": "card",
16    "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
17    "last4": "4242",
18    "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
19    "bin": "424242"
20  },
21  "links": {
22    "self": {
23      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
24    },
25    "action": {
26      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
27    },
28    "void": {
29      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
30    },
31    "capture": {
32      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
33    }
34  }
35}

Configure processor routing
Beta

Information

Get a list of available processors
Beta

Response example

Configure processor rules

Information

Request example

Response example

Information

Get a list of available processors Beta

Response example

Configure processor rules

Information

Request example

Response example

Get a list of available processors
Beta