Advanced Routing Rules
This feature is currently a Private Beta release. Contact Chargebee Support to enable Advanced Routing Rules for your live and test sites.
Routing Rules, part of Advanced Setup in the Payment Optimization Engine, conditionally route transactions to specific gateways to optimize approval rates, cost efficiency, and acquiring strategy.
Benefits of Advanced Routing for your business:
-
Geography-Based Optimization Route transactions to regionally aligned gateways based on billing or shipping country to improve authorization rates without restructuring pricing or plans.
-
Customer Segment-Based Optimization Direct different customer segments (e.g., freemium vs. enterprise) to specific gateways to tailor processing strategy and service levels.
-
Payment Method-Based Optimization Route specific payment methods or APMs to specialized gateways to improve performance and operational efficiency.
-
Card-Based Routing Optimization Route card transactions based on the 6- or 8-digit BIN, card brand, card type, or issuing country to the most suitable gateway.
-
Cost-Aware Routing Distribute traffic to manage cross-border fees, interchange exposure, or gateway pricing models more effectively.
These are just a few examples of how Advanced Routing can benefit your business. The engine is flexible and can be customized to meet your unique payment routing needs, ensuring optimal results.
Supported variables to set routing strategy:
- Payment method
- Customer location (Billing / Shipping address)
- Checkout amount and currency
- Product catalog / Plan in PC 1.0 and Item price in PC 2.0
- Card BIN (6 or 8 digits)
- Card brand
- Card type (credit, debit, or prepaid)
- Card issuing country
If you need more variables, submit a request for them here. We will consider them for our next iteration.
Configuring Routing Rules
Follow these steps to create a new routing rule:
-
Go to the Routing Rules section.
-
Click Create Rule.
-
Configure the rule on the Create Rule page:
- Add the required conditions such as Payment method, Plan, Billing Country, Shipping Country, Invoice Amount, Currency, Card BIN, Card Brand, Card Type, or Card Issuing Country.
- Select the Payment Gateway to be routed when these conditions match.
- Enter a Rule Name.
-
Verify the rule settings and click Publish to activate the rule.
-
The Routing Rules home page will reflect the published rules.
While evaluating rules, if none of the rules match, then the payment gateway configured at the Default Payment Method & Routing step will be used for routing.
Testing Routing Rules
Before deploying a rule, it's essential to test it to ensure it meets your requirements and behaves as expected.
Follow these steps to run a test:
- Navigate to the Routing page and click Run Test.
- Enter values that match the specific rule you want to test.
- Click Run Test to see the results.
If the expected rule appears on the Result page, congratulations! Your rule is correctly configured.
Example
Let's walk through an example:
Suppose you've created a rule with the ID rule_161t4tUbLxeqJ2E0, which states:
"If the invoice amount exceeds 100 euros, the Payment Method is iDEAL, and the currency is EUR, then use the Mollie payment gateway."
To test this rule:
- Enter values matching these conditions.
- Click Run Test.
If the correct routing rule appears in the results, great! Your rule is working as expected. If not, close the Test Routing Rule pop-up, review the rule configuration, and test again.
Routing Rules conditionally route transactions to specific gateways to optimize approval rates, cost efficiency, and acquiring strategy.
Testing card-based routing rules
You can test a card rule by making a test payment on any checkout that uses Payment Components.
Chargebee checks card rules differently on live and sandbox sites:
- Live site: Chargebee uses live BIN data to identify the card's brand, type, and issuing country.
- Sandbox site: Chargebee uses mock card data instead. To test a rule, use one of the example cards in the following table.
Enter the card number with the CVC and expiry date from the same row. Make sure that the card brand is enabled in your gateway account.
On a sandbox site, cards that aren't listed here might not match Card Brand, Card Type, or Card Issuing Country conditions. Live sites aren't affected.
| Routing variable | Value for the variable | Card Number | Card CVC | Card Expiry (Month/Year) | Gateways that support this card |
|---|---|---|---|---|---|
| Card BIN | 424242 or 42424242 | 4242424242424242 | 123 | 12/34 | Stripe, Checkout.com |
| 411111 or 41111111 | 4111111111111111 | 123 | 12/34 | Chargebee Test Gateway | |
| Card Brand | Visa | 4242424242424242 | 123 | 12/34 | Stripe, Checkout.com |
| Visa | 4111111111111111 | 737 | 03/30 | Adyen, Braintree, Cybersource, Chargebee Test Gateway | |
| Visa | 4444333322221111 | 555 | 03/30 | Braintree, Worldpay | |
| Mastercard | 5555555555554444 | 737 | 03/30 | Stripe, Adyen, Braintree, Cybersource, Chargebee Test Gateway | |
| Mastercard | 5436031030606378 | 123 | 12/34 | Checkout.com | |
| Mastercard | 5454545454545454 | 555 | 03/30 | Worldpay | |
| Mastercard | 5431111111111111 | 123 | 10/29 | NMI | |
| Mastercard | 2222420000001113 | 123 | 08/29 | Cybersource, BlueSnap | |
| Amex | 378282246310005 | 1234 | 12/34 | Stripe, Braintree, Cybersource, Mollie, Chargebee Test Gateway | |
| Amex | 370000000000002 | 7373 | 03/30 | Adyen | |
| Amex | 341111111111111 | 1234 | 10/29 | NMI | |
| Discover | 6011111111111117 | 123 | 12/34 | Stripe, Checkout.com, Cybersource, Chargebee Test Gateway | |
| Discover | 6445644564456445 | 737 | 03/30 | Adyen | |
| Discover | 6011000991300009 | 123 | 10/29 | Braintree, NMI | |
| Discover | 6011000400000000 | 555 | 03/30 | Worldpay | |
| Diners Club | 3056930009020004 | 123 | 12/34 | Stripe | |
| Diners Club | 36006666333344 | 737 | 03/30 | Adyen | |
| Diners Club | 36259600000004 | 123 | 12/34 | Braintree | |
| JCB | 3566002020360505 | 123 | 12/34 | Stripe | |
| JCB | 3569990010095841 | 737 | 03/30 | Adyen | |
| JCB | 3530111333300000 | 123 | 12/34 | Braintree, Chargebee Test Gateway | |
| JCB | 3566111111111113 | 123 | 12/34 | Cybersource | |
| UnionPay | 6200000000000005 | 123 | 12/34 | Stripe | |
| UnionPay | 6221261111117766 | 123 | 12/34 | Braintree | |
| Cartes Bancaires | 4000002500001001 | 123 | 12/34 | Stripe | |
| Eftpos Australia | 4000050360000001 | 123 | 12/34 | Stripe | |
| Eftpos Australia | 4089670000000014 | 737 | 03/30 | Adyen | |
| Dankort | 5019555544445555 | 737 | 03/30 | Adyen | |
| Elo | 5066991111111118 | 737 | 03/30 | Adyen | |
| Hipercard | 6062828888666688 | 737 | 03/30 | Adyen | |
| Card Type | Credit | 378282246310005 | 1234 | 12/34 | Stripe, Braintree, Cybersource, Mollie |
| Credit | 4000020000000000 | 737 | 03/30 | Adyen, Checkout.com | |
| Credit | 4444333322221111 | 555 | 03/30 | Braintree, Worldpay | |
| Credit | 5431111111111111 | 123 | 10/29 | NMI | |
| Credit | 2222420000001113 | 123 | 08/29 | Cybersource, BlueSnap | |
| Credit | 2223003122003222 | 123 | 12/34 | Chargebee Test Gateway | |
| Debit | 4000056655665556 | 123 | 12/34 | Stripe | |
| Debit | 4400000000000008 | 737 | 03/30 | Adyen | |
| Debit | 4012000033330125 | 123 | 12/34 | Braintree | |
| Debit | 4659105569051157 | 123 | 12/34 | Checkout.com | |
| Debit | 5163613613613613 | 555 | 03/30 | Worldpay | |
| Prepaid | 5105105105105100 | 123 | 12/34 | Stripe, Chargebee Test Gateway | |
| Prepaid | 5103221911199245 | 737 | 03/30 | Adyen | |
| Prepaid | 4500600000000061 | 123 | 12/34 | Braintree | |
| Card Issuing Country | United States | 378282246310005 | 1234 | 12/34 | Stripe, Braintree, Cybersource, Mollie |
| United States | 4000020000000000 | 737 | 03/30 | Adyen, Checkout.com | |
| United States | 6011000400000000 | 555 | 03/30 | Worldpay | |
| United States | 5431111111111111 | 123 | 10/29 | NMI | |
| United States | 2222420000001113 | 123 | 08/29 | Cybersource, BlueSnap | |
| United States | 2223003122003222 | 123 | 12/34 | Chargebee Test Gateway | |
| United Kingdom | 5555555555554444 | 737 | 03/30 | Stripe, Adyen, Braintree, Cybersource, Chargebee Test Gateway | |
| United Kingdom | 4659105569051157 | 123 | 12/34 | Checkout.com | |
| United Kingdom | 4444333322221111 | 555 | 03/30 | Braintree, Worldpay | |
| Netherlands | 4111111111111111 | 737 | 03/30 | Adyen, Braintree, Cybersource, Chargebee Test Gateway | |
| Canada | 4012000033330729 | 123 | 12/34 | Braintree | |
| Ireland | 4023490000000008 | 123 | 12/34 | Braintree | |
| Germany | 5305484748800098 | 123 | 12/34 | Checkout.com | |
| France | 4977949494949497 | 737 | 03/30 | Adyen | |
| Brazil | 4000000760000002 | 123 | 12/34 | Stripe | |
| Australia | 5163613613613613 | 555 | 03/30 | Worldpay | |
| Japan | 3530111333300000 | 123 | 12/34 | Braintree | |
| Japan | 3566002020360505 | 123 | 12/34 | Chargebee Test Gateway | |
| China | 6221261111117766 | 123 | 12/34 | Braintree | |
| Ukraine | 4012888888881881 | 123 | 12/34 | Chargebee Test Gateway |
Multi-business entity sites
If your site uses multiple business entities, payment optimization settings can be managed at the site level or customized for a specific entity. In general:
- Site-level changes apply to entities that inherit those settings.
- Entity-level customization lets you define routing, defaults, and related rules for a single entity without affecting other entities.
- You can revert an entity to follow the current site-level payment optimization settings when needed.
Overriding inherited payment optimization rules for a business entity gives you a clear slate for that entity: site-level rules no longer apply for that entity until you define new ones. That change can affect how new and in-progress payments are routed and processed for that entity. Review open checkouts, scheduled charges, and recurring behavior before you override, and adjust rules promptly so you do not leave the entity without the routing or defaults you need.
Exact screens and actions can vary slightly by Chargebee version and the features enabled for your account. If you do not see Payment optimization, Default Payment Methods & Routing, or entity controls, contact Chargebee Support.