Skip to main content
On Payment Routing, you decide which of your card gateways handles each card payment. You build rules that send matching payments to a gateway, and you set the default order of gateways for payments that no rule matches.

​
Where to find it

In the admin, click the Settings gear in the top bar. In the Settings sidebar, under Payments, select Payment Routing. To open the screen, your role needs at least View only for Payment Routing, in the Settings card on the role’s Permissions tab. To change rules, the fallback order or test mode, the role needs Full access for Payment Routing. To add a rule, change a rule’s gateway, or add a gateway to the fallback order, your role also needs at least View only for Gateways, in the Settings card. With View only, you can see the rules and the fallback order but can’t change them: Add rule, the edit and delete buttons, Add to order and Save order don’t appear, and the Test mode button is unavailable. An admin manages roles on Roles.

​
What’s on the screen

The top bar holds the Test mode button. See Test mode. If you’ve put countries in test mode, a banner about it appears below the top bar. Below that, one card holds two sections: Routing rules and Default Fallback Order. Only card gateways appear on this screen. For non-card payment accounts, see APM.

​
Routing rules

Rules are evaluated in order, from the top. The first rule a payment matches is the one that’s used. If no rule matches, the payment falls through to the Default Fallback Order below. Until you add a rule, every payment uses the fallback order. Rules and the Default Fallback Order decide which gateway takes checkout payments and payments entered by admins. To limit a rule to orders entered by admins, give it a Cart Source condition with the value admin. Subscription renewals normally don’t follow your rules or the fallback order. A renewal usually stays on the subscription’s own gateway while that gateway is active. If you see CIT (E-commerce), MIT (Recurring) and MOTO (Admin-initiated) tabs on this screen, each tab has its own rules and fallback order, and each rule applies only to its tab’s payments.
Build a rule to control routing. Don’t deactivate a gateway for that: deactivating it immediately fails in-flight transactions on that gateway. Rules don’t move subscription renewals, so keep a gateway’s merchant account open while subscriptions still renew on it.
The Add rule button sits next to the Routing rules heading. With no rules, the section shows No rules yet. Add one to start routing traffic. Each rule in the list shows:
  • A drag handle and the rule’s position in the list.
  • The rule’s name, then an arrow and the gateway it sends payments to. A rule that splits payments lists each gateway with its percentage. Past three gateways, the rest appear as a count, such as +2 more.
  • The rule’s conditions, shown as chips such as payment_source = apple_pay. A rule without conditions shows No conditions — matches all.
  • The pencil (Edit rule) and trash (Delete rule) buttons.
A rule can also show one of these badges:

​
Default Fallback Order

This is the ordered list of gateways used when no rule matches a checkout or admin payment, or when cascading a soft decline. Only active gateways are eligible for routing. Each row shows a drag handle, the gateway’s position, its logo and name, and its gateway type under the name. An inactive gateway is grayed out and shows Not eligible for routing until you activate it. Card gateways that aren’t in the order appear below the list, with a dash instead of a position and a Not in fallback order badge. They’re never used as a fallback until you click Add to order and save. If you don’t have any card gateways yet, the section says No eligible processors. Set up a card gateway on Gateways to fill the list. The Save order button next to the heading saves the order. It stays unavailable until you change something.

​
Add a rule

1

Open the panel

Click Add rule. The Add rule panel opens. The note at the top reminds you that the rule applies to every transaction type unless you add a Cart Source condition.
2

Name the rule

Enter a Rule name. It starts as Rule followed by the next number, such as Rule 3. If you leave it empty, the rule keeps that name.
3

Add conditions

Under Conditions, click Add Condition. A new row appears, set to the first condition you haven’t used yet. Choose the condition you want, and then set its value. See Conditions.A payment must match every condition in the rule, so the rows are joined by AND. To remove a condition, click the trash button at the end of its row. A rule with no conditions matches all payments.
4

Choose the gateway

Under Routing, click Add Processor. A row appears with a gateway already picked. Choose the gateway you want from its list. An inactive gateway shows Inactive — activate to route. A rule that targets it falls through to the default fallback order until you activate the gateway.
5

Split payments, if you want

To split matching payments across gateways, click Add Processor again for each gateway, and then enter a percentage for each one. The Total must equal 100%. Each time you add or remove a gateway, the percentages reset to an even split, so enter them after you’ve added all your gateways. To remove a gateway from the split, click the trash button on its row.
6

Choose whether it's active

The switch at the bottom of the panel reads Active for a new rule. Turn it off to keep the rule but skip it during routing. The label changes to Inactive.
7

Save

Click Save rule. The button is available once every condition has a value, the rule has at least one gateway, and split percentages total 100%. The new rule goes to the bottom of the list.
A new rule starts at the bottom of the list, so a broader rule above it can catch its payments first. If the new rule shows Unreachable (caught by …), drag it above the rule named in the badge.

​
Conditions

Conditions you can use include: You can use each condition once in a rule. For a condition that takes one value, choosing another value replaces the first.

​
Edit a rule

1

Open the rule

Click the pencil (Edit rule) on the rule’s row. The Edit rule panel opens.
2

Make your changes

Change the name, conditions, gateways or the Active switch, as described in Add a rule.
3

Save

Click Update rule.

​
Reorder rules

Drag a rule by its handle to a new position. The new order saves right away. If the save fails, you see an error and the list goes back to its previous order.

​
Delete a rule

1

Choose Delete

Click the trash (Delete rule) on the rule’s row.
2

Confirm

In the Delete rule dialog, click Delete. This can’t be undone.
If you delete your last rule, every payment uses the default fallback order.

​
Change the default fallback order

1

Arrange the gateways

Under Default Fallback Order, drag each gateway by its handle into the order you want. The positions update as you go.
2

Add missing gateways

For a gateway marked Not in fallback order, click Add to order. It joins the end of the list, and you can drag it into place.
3

Save

Click Save order. A message confirms that the order was updated.

​
Test mode

Test mode works only after it’s turned on for your company, and it’s off by default. Until then, the Test mode panel shows Not active until enabled. The countries you select are saved, but all payments keep routing normally.
When test mode is on, traffic from the countries you select bypasses your rules and routes to the test gateway. Other countries route normally. Use test mode to exercise integration flows without charging customers. Apple Pay payments from those countries are declined, and so is any payment the test gateway can’t take, such as a recurring or admin payment on a test gateway without that transaction type. Once test mode is on, a country you add on the Countries screen starts in test mode, so deselect it before you start selling there.
1

Open the panel

Click Test mode in the top bar. The Test mode panel opens.
2

Choose the test gateway

Select a Test gateway. The list shows your card gateways that have Test Only or Sandbox Mode turned on in Gateways. If you don’t have one, the panel shows No test gateway configured, and you can’t add countries until a test gateway exists.
3

Select countries

Under Countries in test mode, click a country to select or deselect it. Select all adds every country the test gateway is assigned to, and Deselect all clears the list. A country the test gateway isn’t assigned to shows the gateway’s name followed by not assigned, and you can’t add it.
4

Save

Click Save. The button is available once you’ve changed something. The panel closes when the change is saved.
After you save, the button shows how many of your countries are selected, such as Test mode: 2/12 Countries (not active). A Test mode is configured but not active banner says that all payments keep routing normally, and lists the selected countries and the test gateway they’re set to use. It also lists any selected country without a usable test gateway, whose payments would be declined once test mode is on. To take a country out of test mode, deselect it and click Save.

​
Frequently asked questions

Add a rule with no conditions so that it matches every payment, and add each gateway under Routing with its percentage. The percentages must total 100%. Rules above it still run first. To split only some payments, add conditions to the rule.
They fall through to the Default Fallback Order. The same happens to payments that match a rule whose gateway is inactive. If you have no rules, every checkout and admin payment uses the fallback order. Subscription renewals don’t use it. See Routing rules.