Guides
Start typing to search…

Payment Router Logic

The payment router evaluates multiple rules in a specific order to determine which merchant processes each transaction.

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.

The Decision Flow

Step 1: API Overrides Check

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

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.

Step 5: Reattempt Restrictions (Exclusion)

Purpose: Don't retry on similar merchants

If this is a reattempt (customer already declined once), the system can exclude merchants similar to the one that declined. Similarity is based on:

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

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

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.

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 transaction volume per merchant

The router checks each merchant's cap settings:

  • Daily/weekly/monthly transaction limits
  • Current transaction count in that timeframe
  • Whether cap applies to this route only or all routes

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

Why this matters: Caps let you manage risk, test new processors with limited volume, or stay within processor-imposed limits.

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.

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

Why this matters: New processors often require minimum monthly volume. Priority ensures they get it.

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: Payment Router Setup

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

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


Updated about 3 hours ago