Route payments between gateways¶
This page covers two features that get confused with each other constantly, because they both involve "picking a different gateway" — but they solve different problems and are configured in different places.
Routing decides ahead of time. Fallback reacts to a failure.
Gateway routing picks which gateway to try before a charge is attempted, using rules you write — by amount, currency, country or payment mode. Gateway fallback does not pick ahead of time — it reacts: if the gateway a charge was already sent to declines it, ChargeOn automatically retries the identical charge on a backup gateway. You can use both together: routing decides the first gateway tried, and fallback takes over only if that attempt fails. Fallback works only for card payments on gateways running in Direct API mode — see gateway fallback below.
Gateway routing¶
Criteria-based routing picks the payment gateway for a transaction automatically, using rules you define. Instead of always using the same preferred gateway, ChargeOn evaluates your rules when the charge form opens and selects the best gateway for that transaction — by amount, currency, country or payment mode.
Routing is off by default. With it off, ChargeOn behaves as it always has and uses the preferred gateway. With it on, rules are evaluated in priority order and the first match wins. If nothing matches, the preferred gateway is used.
Before you start¶
- At least two connected and verified gateways — routing between one gateway and itself achieves nothing
- Each target gateway must be active and linked to the ChargeOn record
- Permission to edit the ChargeOn record
Turn routing on¶
- Open a ChargeOn record.
- Click the Configure Routing quick action. A full-screen panel opens — the rules list on the left, the detail and edit panel on the right.
- Switch the toggle at the top of the screen on.
| Toggle | What happens at charge time |
|---|---|
| Off (default) | The preferred gateway is selected, as before |
| On | Rules are evaluated in order; the first match selects its gateway |
The toggle takes effect immediately and persists across sessions.
Create a rule¶
- Click Add Rule at the top right of the left panel. The right panel switches to edit mode.
- Fill in the rule:
- Rule Name — the editable heading at the top of the right panel. Required. Make it describe the intent, for example "High-value USD to Authorize.Net"
- Target Gateway — the gateway to use when this rule matches
- Active — leave on. Turning it off disables the rule without deleting it
- Click Add Criteria, then fill each row: Field, Operator, Value.
- Click Save at the bottom of the right panel.
New rules are added at the end of the priority order. You can reorder them afterwards.
Fields you can match on¶
| Field | What it is | Type | Examples |
|---|---|---|---|
| Amount | The transaction amount | Number | 100, 500.50, 1000 |
| Currency Code | ISO currency code | Text | USD, EUR, GBP, INR |
| Country | Billing country code | Text | US, CA, GB, DE |
| Payment Mode | How the payment is being taken | Text | INSTANT, SCHEDULED, RECURRING |
| Payment Type | The payment method type | Text | CARD, BANK, ACH, LINK |
Payment Type rules will not fire on the charge form
Routing is evaluated when the charge form opens, and at that moment the user has not yet chosen card, bank or ACH. A rule with a Payment Type criterion has nothing to match against, so it is skipped. Use Amount, Currency Code, Country or Payment Mode instead.
Operators¶
| Operator | What it does | Works with | Example |
|---|---|---|---|
| Equals | Exact match, case-insensitive | Text, Number | Currency Code Equals USD |
| Not Equals | Does not match | Text, Number | Country Not Equals US |
| Greater Than | Numeric greater than | Number only | Amount Greater Than 1000 |
| Less Than | Numeric less than | Number only | Amount Less Than 50 |
| Greater Than or Equal | Numeric at least | Number only | Amount Greater Than or Equal 500 |
| Less Than or Equal | Numeric at most | Number only | Amount Less Than or Equal 100 |
| In | Value appears in a comma-separated list | Text | Currency Code In USD,EUR,GBP |
| Not In | Value does not appear in the list | Text | Country Not In CN,RU |
Criteria combine with AND¶
Every criterion in a rule must match for the rule to fire. A rule with Currency Code Equals USD
and Amount Greater Than 1000 matches only transactions that are both in USD and over
$1,000.
There is no OR. To express "USD or EUR", use one criterion with the In operator.
How rules are evaluated¶
- Rules run from the top of the list downwards.
- The first rule that matches selects the gateway. Evaluation stops there.
- If no rule matches, the preferred gateway is used.
- Inactive rules are skipped.
- Priority is the list order. There is no priority number shown in the interface.
Order matters more than people expect. A broad rule near the top will shadow every specific rule below it.
Manage existing rules¶
Edit a rule¶
- Click the rule in the left panel to select it.
- Click Edit at the top right of the detail panel.
- Change the name, gateway, active flag or criteria.
- Click Save, or Cancel to discard.
An Unsaved badge appears in the header while you have pending changes.
Reorder rules¶
Each rule card in the left panel has up and down arrows next to Priority. Clicking one swaps the rule with its neighbour. The list updates immediately.
Deactivate a rule¶
Turn the Active toggle off inside the edit form. Inactive rules are skipped at charge time and appear in grey in the left panel. The status shows in the rule's detail view but not on the list cards.
Deactivating is the safe way to test whether a rule is causing a problem. It is reversible; deleting is not.
Delete a rule¶
Deleting is permanent
The rule and all its criteria are removed and cannot be recovered. Deactivate instead unless you are certain.
- Select the rule in the left panel.
- Click Delete in the detail panel header.
- Confirm in the dialog.
Examples¶
Send high-value US dollar transactions to Authorize.Net
| Setting | Value |
|---|---|
| Rule Name | High-value USD to Authorize.Net |
| Target Gateway | Authorize.Net |
| Criterion 1 | Currency Code Equals USD |
| Criterion 2 | Amount Greater Than 1000 |
Send Australian transactions to FatZebra
| Setting | Value |
|---|---|
| Rule Name | AUD to FatZebra |
| Target Gateway | FatZebra |
| Criterion 1 | Currency Code Equals AUD |
Send Indian transactions to Razorpay
| Setting | Value |
|---|---|
| Rule Name | INR to Razorpay |
| Target Gateway | Razorpay |
| Criterion 1 | Currency Code Equals INR |
What routing does not do¶
| Limitation | What it means for you |
|---|---|
| Payment Type is unavailable at form load | Rules using it never match during auto-selection. See the warning above |
| Country needs a billing address | If the billing address has no country, country rules cannot match |
| The user can override | The selected gateway is a recommendation, not a lock. Users can change it in the dropdown |
| Interactive charges only | Routing applies to the charge form. Scheduled, recurring and batch payments are not affected |
That last one catches people out. If you need a recurring payment to use a specific gateway, set it on the recurring payment itself, not with a routing rule.
If routing does not work¶
| Problem | What to check |
|---|---|
| A rule is not matching | Check every criterion value matches exactly — text comparison ignores case, but USD with a trailing space will not match USD. Confirm the rule is active, and that no broader rule sits above it in the list |
| The gateway is missing from the dropdown | The target gateway must be active and linked to the ChargeOn record via a ChargeOn Gateway Link |
| The routing toggle turns itself off after saving | Your permission set may not grant edit access on the routing field. Ask your administrator |
| The charge form still shows the gateway selection screen | Routing is enabled per ChargeOn record. Confirm you enabled it on the record the charge form is using |
| "No payment gateways support..." | This is a currency problem, not a routing one. The gateways available do not support the transaction's currency |
| "Rule name required" when saving | Enter a name in the editable heading at the top of the edit panel |
Gateway fallback¶
Fallback is ChargeOn's automatic resilience feature: if the gateway a charge was sent to declines it, ChargeOn retries the same charge on a backup gateway, without the customer having to do anything or re-enter their card. It is configured on your ChargeOn mapping record, not the routing panel above — see map ChargeOn fields to your objects.
Before you start¶
- At least two gateways running in Direct API checkout experience — see the restriction below. Fallback between one gateway and itself, or to a Hosted Fields or Redirect gateway, achieves nothing.
- Permission to edit the ChargeOn record.
Turn fallback on¶
- Open your ChargeOn record.
- Set Select Fallback Type to Payment Gateway. The Fallback Gateways list only appears once this is set.
- Under Fallback Gateways, move up to three gateways from Available to Selected.
- Use the up and down arrows to arrange them in the order you want them tried — first in the list is tried first.
- Click Save.
How it works at runtime¶
- A customer submits a payment → the primary gateway attempts the charge.
- If the primary fails → ChargeOn retries on Fallback Gateway 1.
- If that fails → retries on Fallback Gateway 2, then Fallback Gateway 3.
- If every gateway fails → the payment fails, with a combined error message.
Before the primary charge is even attempted, ChargeOn tokenises the card on every fallback gateway at the same time — so a fallback retry never needs the customer to re-enter their card details.
Fallback only works for card payments on Direct API gateways
A gateway running Hosted Fields or Redirect checkout cannot take part in fallback — either as the primary gateway or as a backup. Fallback works by re-sending the raw card number to a different gateway, and for Hosted Fields and Redirect, ChargeOn never has the raw card number to re-send: the customer entered it directly inside the gateway's own form. See choose a checkout experience. Bank payments and Payment Link transactions do not fall back either way, for the same reason.
A recurring payment plan whose very first charge succeeds on a backup gateway stays on that gateway for the rest of its life — fallback is a one-time decision at the start of the plan, not something re-evaluated every cycle.
For exactly which gateways can take part in fallback and under what condition, see the gateway reference.
If fallback does not work¶
| Symptom | Likely cause | What to do |
|---|---|---|
| A gateway in your Fallback Gateways list is never actually tried | It is not currently running in Direct API checkout experience | Check its Checkout Experience and switch it, or choose a different backup gateway |
| Fallback did not retry after a decline | Only card payments on Direct API gateways fall back — bank payments and Payment Link do not | Confirm the failed payment was a card charge on a Direct API gateway |
| A recurring payment stayed on a backup gateway after its first cycle fell back to it | Expected — a plan's gateway is fixed from its first successful charge onward | No action needed unless you want to move the plan to a different gateway manually |