Routing Rules
Boost a specific provider for a given country, channel, currency, or amount range — within its priority tier.
A routing rule matches on a payment's country/channel/currency/amount and, when it matches, adds a scoring boost to one target provider (and optionally names a single fallback provider).
A rule does not define an ordered provider list
This page previously described a rule as holding conditions (a nested object) plus an
ordered providers: [...] array that became "the" fallback chain. That's not how it works. A
rule targets one provider_id (and optionally one fallback_provider_id); its match only
contributes a tie-break boost used to order candidates within the same priority tier. The
fallback chain itself is determined by priority tiers, not by a
rule's provider list.
Anatomy of a rule
namestringrequiredcountry_codestringoptionalchannelstringoptionalcurrencystringoptionalmin_amount / max_amountamountoptionalprovider_idstringrequiredfallback_provider_idstringoptionalpriorityintegeroptionalweightintegeroptionaltime_windows / customer_segments / metadata_filters / frequency_capsobject[]optionalThe boost a matching rule contributes is base_rule_match (configurable, default 1000) plus a
smaller bonus per specific field the rule constrains (country/channel/currency/amount), plus the
rule's own priority. If several active rules match the same payment for the same provider, the
highest-scoring one wins; the boost is then compared against every other candidate's score —
within the same TeamProvider priority tier only. A rule can never pull a lower-priority
provider ahead of a higher-priority one.
Example
Boost MTN MoMo for Cameroon mobile-money payments up to 500,000 XAF, with Orange Money as this rule's named fallback:
{
"name": "momo-cm-mtn-first",
"priority": 100,
"country_code": "CM",
"channel": "mobile_money",
"max_amount": 500000,
"provider_id": "prov_mtn_momo_uid",
"fallback_provider_id": "prov_orange_money_uid"
}Route by amount
Above a threshold, boost a different provider — each amount bracket needs its own rule, since one rule targets one provider:
[
{ "name": "small-amounts", "max_amount": 100000, "provider_id": "prov_wave_uid" },
{ "name": "large-amounts", "min_amount": 100001, "provider_id": "prov_bank_uid" }
]Test your rules in sandbox
Create or edit rules in the test environment, make a test payment, then check
Konsole → Routing Log — each candidate row shows its
rule_id/rule_boost if a rule contributed to its score, so you can confirm your rule matched
as expected.
A rule never overrides priority
If the provider your rule targets sits in a lower priority tier than another eligible provider, the rule's boost will not help — that other, higher-priority provider is still tried first. Make sure the provider a rule is meant to favor is actually at the priority tier you expect.