Introducing the Chargebee CLI

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:

  1. Go to the Routing Rules section.

  2. Click Create Rule.

  3. 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.
  4. Verify the rule settings and click Publish to activate the rule.

  5. 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:

  1. Navigate to the Routing page and click Run Test.
  2. Enter values that match the specific rule you want to test.
  3. 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 variableValue for the variableCard NumberCard CVCCard Expiry (Month/Year)Gateways that support this card
Card BIN424242 or 42424242424242424242424212312/34Stripe, Checkout.com
411111 or 41111111411111111111111112312/34Chargebee Test Gateway
Card BrandVisa424242424242424212312/34Stripe, Checkout.com
Visa411111111111111173703/30Adyen, Braintree, Cybersource, Chargebee Test Gateway
Visa444433332222111155503/30Braintree, Worldpay
Mastercard555555555555444473703/30Stripe, Adyen, Braintree, Cybersource, Chargebee Test Gateway
Mastercard543603103060637812312/34Checkout.com
Mastercard545454545454545455503/30Worldpay
Mastercard543111111111111112310/29NMI
Mastercard222242000000111312308/29Cybersource, BlueSnap
Amex378282246310005123412/34Stripe, Braintree, Cybersource, Mollie, Chargebee Test Gateway
Amex370000000000002737303/30Adyen
Amex341111111111111123410/29NMI
Discover601111111111111712312/34Stripe, Checkout.com, Cybersource, Chargebee Test Gateway
Discover644564456445644573703/30Adyen
Discover601100099130000912310/29Braintree, NMI
Discover601100040000000055503/30Worldpay
Diners Club305693000902000412312/34Stripe
Diners Club3600666633334473703/30Adyen
Diners Club3625960000000412312/34Braintree
JCB356600202036050512312/34Stripe
JCB356999001009584173703/30Adyen
JCB353011133330000012312/34Braintree, Chargebee Test Gateway
JCB356611111111111312312/34Cybersource
UnionPay620000000000000512312/34Stripe
UnionPay622126111111776612312/34Braintree
Cartes Bancaires400000250000100112312/34Stripe
Eftpos Australia400005036000000112312/34Stripe
Eftpos Australia408967000000001473703/30Adyen
Dankort501955554444555573703/30Adyen
Elo506699111111111873703/30Adyen
Hipercard606282888866668873703/30Adyen
Card TypeCredit378282246310005123412/34Stripe, Braintree, Cybersource, Mollie
Credit400002000000000073703/30Adyen, Checkout.com
Credit444433332222111155503/30Braintree, Worldpay
Credit543111111111111112310/29NMI
Credit222242000000111312308/29Cybersource, BlueSnap
Credit222300312200322212312/34Chargebee Test Gateway
Debit400005665566555612312/34Stripe
Debit440000000000000873703/30Adyen
Debit401200003333012512312/34Braintree
Debit465910556905115712312/34Checkout.com
Debit516361361361361355503/30Worldpay
Prepaid510510510510510012312/34Stripe, Chargebee Test Gateway
Prepaid510322191119924573703/30Adyen
Prepaid450060000000006112312/34Braintree
Card Issuing CountryUnited States378282246310005123412/34Stripe, Braintree, Cybersource, Mollie
United States400002000000000073703/30Adyen, Checkout.com
United States601100040000000055503/30Worldpay
United States543111111111111112310/29NMI
United States222242000000111312308/29Cybersource, BlueSnap
United States222300312200322212312/34Chargebee Test Gateway
United Kingdom555555555555444473703/30Stripe, Adyen, Braintree, Cybersource, Chargebee Test Gateway
United Kingdom465910556905115712312/34Checkout.com
United Kingdom444433332222111155503/30Braintree, Worldpay
Netherlands411111111111111173703/30Adyen, Braintree, Cybersource, Chargebee Test Gateway
Canada401200003333072912312/34Braintree
Ireland402349000000000812312/34Braintree
Germany530548474880009812312/34Checkout.com
France497794949494949773703/30Adyen
Brazil400000076000000212312/34Stripe
Australia516361361361361355503/30Worldpay
Japan353011133330000012312/34Braintree
Japan356600202036050512312/34Chargebee Test Gateway
China622126111111776612312/34Braintree
Ukraine401288888888188112312/34Chargebee 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.