Payment Router Logic

Understanding how the payment router makes decisions is key to configuring it effectively. When a transaction comes through, the router first retrieves all available merchants from the router based on the payment method, card type, and whether each merchant is active and hasn't hit their processing limits. From this initial pool of available merchants, the router then applies a series of rules that either prioritize certain merchants or exclude others from consideration. Finally, if multiple merchants remain, the router applies your configured routing method (Round Robin, Weighted, or Volume) to make the final selection.

To see how these decisions appear in practice, check out How to Read the Route Log.

The Decision Flow

Step 1: API Overrides Check

First priority: If merchant_id is passed via API, the router selection logic is bypassed and that merchant is used directly—skipping all routing rules below.

Important: Even when passing merchant_id, the system still validates:

• Payment method support (merchant accepts the payment method)
• Card type support (merchant accepts the card type if paying with credit card)
• Processing limits (merchant hasn't exceeded monthly limits)
• BIN blocks (card BIN is not blocked on the merchant)

Note: When using API overrides, you will not see any Route Logs since the router logic is bypassed.

Learn more: API Overrides

Step 2: Max Attempts Check

Purpose: Fraud prevention

If your router has max attempts enabled, the system checks how many transaction attempts have been made for this specific order. Once the limit is reached, no further processing is allowed.

Learn more: Max Attempts

Step 3: Get Available Merchants

The router queries all merchants assigned to the router that match:

• The payment method (credit card, PayPal, Apple Pay, etc.)
• The card type (Visa, Mastercard, Amex, etc.) if paying with credit card
• Merchant is active
• Merchant is active on the router
• Merchant hasn't exceeded their monthly processing limit

This initial list is the pool of merchants the router will evaluate. All subsequent steps either exclude merchants from this pool or prioritize specific merchants within it.

Step 4: Merchant Groups (Inclusion)

Purpose: Force specific customers to use specific merchants

If the customer belongs to a merchant group, the router checks each merchant in that group:

If the customer does NOT have a successful order with that merchant:

• Include the merchant (force it to be used)

If the customer already has a successful order with that merchant:

• Exclude the merchant (prevents duplicate orders on same merchant)

This ensures one successful order per merchant per customer within the group.

Note: If all merchants in the group become excluded (customer has orders on all of them), see Step 9: Merchant Group Fallback for how this is handled.

Learn more: Merchant Groups

Step 5: Reattempt Restrictions (Exclusion)

Purpose: Don't retry on similar merchants

This step handles two types of reattempts differently:

Auto Reattempts (Initial Decline Reattempts): When the router automatically reattempts a declined transaction, it ALWAYS excludes the merchant that just declined. The system then checks if reattempt restrictions are enabled and excludes merchants with similar characteristics:

• Same gateway (e.g., all other Authorize.Net merchants)
• Same processor (e.g., all other First Data merchants)
• Same category (e.g., all other high-risk processors)

Manual Reattempts (Customer tries again later): If the customer has previous transactions and reattempt restrictions are enabled, the system identifies previously used merchants and excludes those with similar characteristics based on the restriction type.

Reattempt on Previously Used Merchant setting:

• If OFF (default): Exclude all similar merchants including previously used ones
• If ON: Exclude all similar merchants but allow previously used merchants to be tried again

Why this matters: If one Authorize.Net merchant declines a card, other Authorize.Net merchants will likely decline too. This prevents wasting attempts on similar processors.

Learn more: Initial Decline Reattempts

Step 6: BIN Blocks (Exclusion)

Purpose: Exclude merchants that don't accept specific card types

If you've configured BIN blocking on merchants, the router checks the card's BIN number and excludes any merchants that block it.

Why this matters: Some processors don't accept prepaid cards, international cards, or specific bank cards. BIN blocking prevents sending those cards to processors that will decline them.

Learn more: How to Add BIN Blocks

Step 7: Item-Based Routing (Inclusion/Exclusion)

Purpose: Route based on cart contents

If you've configured items on merchants, the router checks what's in the cart:

Force Items ON: Only merchants that support ALL cart items can be used Force Items OFF: Merchants without item restrictions OR merchants with all required items can be used

Why this matters: Certain products (CBD, supplements, high-ticket items) may only be allowed by specific processors. Item routing ensures you only send orders to processors that accept those products.

Learn more: Item-Based Routing

Step 8: Order Caps (Exclusion)

Purpose: Limit initial transaction volume per merchant

The router checks each merchant's cap settings:

• Daily/weekly/monthly transaction limits for cycle 1 (initial orders only)
• Current transaction count in that timeframe
• Whether cap applies to this route only or all routes

If a merchant has hit their cap for initial transactions, they're excluded from selection.

Note: Order caps only apply to cycle 1 initial transactions, not rebills or subsequent cycles.

Learn more: Priorities and Caps

Step 9: Merchant Group Fallback

Purpose: Handle when all merchant group merchants are exhausted

This step only applies if the customer belongs to a merchant group AND after applying all the exclusion rules above (reattempt restrictions, BIN blocks, item routing, order caps), there are no merchants remaining.

Fallback Option 1: Decline the sale

• Transaction declines with error "No merchant found for customer merchant group"
• Customer cannot place another order

Fallback Option 2: Use router settings

• Ignore the merchant group restrictions
• Re-query merchants using only item routing and reattempt restrictions
• Apply order caps again
• Continue to routing method selection

The fallback behavior is configured in the merchant group settings.

Step 10: No Merchants Available Error

If no merchants remain after applying all the exclusion rules above, the transaction declines with error "No merchants available" or "No merchant found for customer merchant group."

How to troubleshoot: Check the Route Log tab on the order to see which rules excluded which merchants.

Learn more: Payment Router Troubleshooting

Step 11: BIN Priority (Inclusion)

Purpose: Force specific merchants for specific card BINs

This overrides everything below it. If a card BIN matches a priority BIN profile, only those merchants are used—regardless of routing method, weights, or other settings.

Why this matters: If you know certain BINs perform better on specific processors, BIN priority routes them there automatically.

Learn more: Activating BIN Priorities

Step 12: Priority Settings (Inclusion)

Purpose: Guarantee minimum transaction volume to a merchant

If a merchant has priority enabled and hasn't reached their priority limit for the timeframe, that merchant will be used exclusively until the limit is met.

Priority vs Cap:

• Priority forces merchant to get transactions first
• Cap prevents merchant from getting too many transactions
• A merchant can have both priority and cap

Learn more: Priorities and Caps

Step 13: Single Merchant Check

If only one merchant remains after all the rules above, that merchant is selected with reason "only merchant remaining in router."

Step 14: Routing Method Selection

If multiple merchants remain, the router applies your configured routing method:

Round Robin: Rotate evenly across merchants in sequence Weighted: Distribute by percentage across merchants Volume: Route to merchants with most remaining monthly capacity

Learn more: Initial Transaction Routing (ITR) Types

Step 15: Final Selection

The routing method returns one merchant, logs the decision to the Route Log, and the transaction is processed.

How to Use This Information

When configuring your router:

1. Start with routing method only (Round Robin or Weighted)
2. Test to verify distribution works correctly
3. Add advanced features one at a time
4. Test after each change

When troubleshooting:

1. Check the Route Log on the order
2. Follow the decision flow above
3. Identify which step excluded merchants
4. Adjust configuration or rules as needed

Learn more: Payment Router Troubleshooting

Understanding priority order:

• API overrides beat everything
• BIN Priority beats routing method
• Priority Settings beat routing method
• Routing method is last resort (when multiple merchants available)

Rule Interaction Examples

Example 1: Priority + Cap on Same Merchant

Configuration:

• Merchant A: Priority 10 transactions/day, Cap 50 transactions/day
• Merchant B: No priority, no cap

What happens:

• First 10 transactions today → Merchant A (priority)
• Next 40 transactions today → Normal routing (priority met, both merchants available)
• After 50 transactions → Merchant B only (Merchant A hit cap)

Example 2: Merchant Groups + Item Routing

Configuration:

• Customer in Group X (Merchant A, Merchant B)
• Cart has CBD product (only Merchant B and Merchant C support CBD)

What happens:

• System wants to use Group X merchants (A, B)
• System checks which Group X merchants support CBD items
• Only Merchant B supports CBD and is in Group X
• Merchant B is selected

Example 3: Reattempt with Restrictions

Configuration:

• First attempt declined on Merchant A (Authorize.Net gateway)
• Reattempt restrictions set to "Gateway"
• Route has Merchant A, B (both Authorize.Net), and Merchant C (NMI gateway)

What happens:

• First attempt → Merchant A (declined)
• Reattempt excludes all Authorize.Net merchants (A, B)
• Only Merchant C remains
• Merchant C is selected

Related Documentation

• Payment Router Setup
• Router Setup Guide
• Initial Decline Reattempts
• Auto-Deactivation
• Item-Based Routing
• Priorities and Caps
• Max Attempts
• Payment Router Troubleshooting