Multi-Gateway Cascading

Multi-gateway cascading automatically routes failed payment retries through alternative payment processors when the primary gateway declines. Instead of retrying the same PSP repeatedly, LostChurn cascades the charge through your connected gateways in priority order, maximizing recovery while minimizing processing costs. This feature is available on Revenue Command and Enterprise tiers.

How Cascading Works

When a payment retry is declined by the primary payment processor, LostChurn evaluates whether the decline is eligible for cascading. If it is, the system automatically submits the charge to the next gateway in your cascade chain.

Cascade Eligibility

Not all declines should be cascaded. LostChurn only cascades when there is a reasonable chance a different processor will succeed:

Configuring Your Cascade Chain

Plan Eligibility

Gateway cascading requires a Revenue Command or Enterprise plan. The system checks your plan tier when you attempt to enable cascading or add gateway configurations. If you are on the Engine or Recovery tier, you will see a prompt to upgrade.

Connecting Multiple PSPs

Before configuring cascading, connect at least two payment processors in Settings > Integrations. LostChurn supports cascading across any combination of supported PSPs, including:

• Stripe
• Braintree
• Adyen
• Checkout.com
• PayPal (Braintree gateway)
• Worldpay
• And others

Adding a Gateway

Use the upsert_gateway_config reducer (or the Settings UI) to add or update a gateway in your cascade chain. Each gateway configuration requires:

If a gateway configuration already exists for the same merchant + provider combination, it is updated rather than duplicated.

Removing a Gateway

To remove a gateway from your cascade chain, use the delete_gateway_config reducer or click Remove next to the gateway in Settings > Gateway Cascade. You need to be the merchant owner to delete a gateway configuration.

Priority Ordering

Navigate to Settings > Gateway Cascade to configure your cascade chain. Set the priority for each PSP (lowest number = highest priority):

1. Primary -- Your default processor. All initial charges and first retries go here.
2. Secondary -- First fallback. Used when the primary declines with a cascade-eligible code.
3. Tertiary -- Second fallback. Used when both primary and secondary decline.
4. Quaternary -- Third fallback (Enterprise only). Additional failover capacity.

The getGatewayCascadeOrder function builds the cascade order by:

1. Filtering out inactive gateways and those with Open circuit breakers
2. Sorting healthy gateways by the chosen strategy (priority or cost)
3. Appending Half-Open gateways at the end (for probe traffic)
4. Promoting a preferred provider to first position if specified
5. Trimming to the configured maxDepth

Enabling and Configuring Cascade

Use the toggle_cascade reducer or Settings > Gateway Cascade > Enable to turn cascading on or off. When enabling, you can also configure:

These settings are stored in the merchant's settings_json and can be updated at any time. When disabling cascade, your gateway configurations are preserved but retries will only use the primary PSP.

Exclusion Rules

You can exclude specific PSPs from the cascade for certain scenarios:

• By card brand -- Route Amex only through PSPs with favorable Amex rates
• By currency -- Route EUR transactions through European acquirers for better approval rates
• By amount -- Route high-value transactions (above a threshold) through your most reliable PSP
• By decline code -- Skip specific PSPs for certain decline categories

Configure exclusion rules in the Advanced tab of the gateway cascading settings.

Cost Weights

Each PSP charges different processing fees. Configure cost weights in basis points (bps) for each gateway in Settings > Gateway Cascade. For example, 290 bps = 2.90%.

When you select the Cost Optimized cascade strategy, LostChurn routes to the cheapest viable PSP first (breaking ties by priority). When using the default Priority Order strategy, cost weights are informational only.

Max Cascade Depth

Configure the maximum number of gateways to try per retry attempt (default: 3, max: 10). Each cascade step counts as a separate retry attempt for billing and velocity purposes.

The getNextGateway function determines the next gateway to try after a failure by filtering out inactive gateways, open circuit breakers, and already-attempted providers, then sorting by the chosen strategy.

Cost-Optimized Routing

Beyond simple failover, LostChurn's cost optimizer evaluates every retry decision against the expected value of the transaction:

Expected Value = (Recovery Probability x Transaction Amount) - Processing Cost

The optimizer considers:

• Historical approval rates per PSP for the specific decline code
• Card brand and issuer affinity with each processor
• Geographic routing -- domestic vs. cross-border processing paths
• Time-of-day patterns -- some PSPs have better approval rates during certain hours
• Processing fees -- including all applicable surcharges

This means LostChurn does not blindly follow the priority order. If your secondary PSP has a significantly higher approval rate for a specific decline code, it may be tried first for that scenario.

PSP Health Monitoring & Circuit Breaker

LostChurn monitors PSP health in real-time using a three-state circuit breaker and automatically routes retries away from processors experiencing elevated failure rates.

Circuit Breaker States

Each gateway has a three-state circuit breaker with the following constants (defined in gateway-cascade.ts):

The three states and their transitions:

Sliding window behavior: Failures are only counted within the FAILURE_WINDOW_MS window. If a failure occurs after the window resets, the failure count starts over at 1. This prevents old, resolved issues from keeping a circuit open.

Half-Open probe behavior: When a gateway transitions to Half-Open, it is placed at the end of the cascade order. This means it only receives traffic if healthier gateways fail first, limiting exposure during the probing phase. A single failure in Half-Open immediately reopens the circuit and resets the success counter.

Health Dashboard

Monitor PSP health in Settings > Gateway Cascade. Each gateway shows:

• Current circuit breaker state (Closed / Open / Half-Open)
• Failure count in the current sliding window
• Half-open probe success count
• Cost weight for cost-optimized routing

You can manually reset a tripped circuit breaker using the reset_circuit_breaker reducer or by clicking Reset in the dashboard. This sets failure_count to 0, circuit_breaker_open to false, and half_open_successes to 0, restoring the gateway to normal operation.

Edge Worker Circuit Breaker

In addition to the SpacetimeDB circuit breaker, a complementary KV-based circuit breaker runs at the Cloudflare Worker edge layer. It uses similar three-state logic with configurable thresholds:

Per-Merchant Circuit Isolation

Circuit breakers are scoped to each merchant-gateway pair, not globally. If one merchant's Stripe integration experiences elevated failures (e.g., due to an expired API key), only that merchant's Stripe circuit opens. Other merchants using Stripe are unaffected, and the affected merchant's other gateways remain available for cascading.

This isolation prevents a single merchant's integration issue from degrading recovery for the entire platform.

Cascade Trail Visualization

Every payment that goes through the cascade chain gets a detailed trail record. View it in the Recovery Detail page for any payment.

Trail Information

The cascade trail shows:

• Attempt number -- Sequential number in the cascade chain
• PSP used -- Which payment processor handled this attempt
• Decline code -- The raw decline code returned
• Response time -- How long the PSP took to respond
• Cost -- Estimated processing cost for the attempt
• Cascade decision -- Why the system chose to cascade (or stop)

Example Trail

Attempt 1: Stripe -> Declined (do_not_honor) -> 245ms -> Cascade: eligible
Attempt 2: Braintree -> Declined (processor_declined) -> 312ms -> Cascade: eligible
Attempt 3: Adyen -> Approved -> 198ms -> Payment recovered
Total cascade cost: $0.30 + $0.25 + $0.22 = $0.77

Analytics

Cascade performance metrics are available in Recovery Metrics:

• Cascade recovery rate -- Percentage of cascaded payments that were eventually recovered
• Average cascade depth -- How many PSPs were tried on average before recovery
• Cascade cost per recovery -- Average total processing cost for cascaded recoveries
• PSP contribution -- Breakdown of recoveries by position in the cascade chain

Best Practices

1. Start with two PSPs -- Add a secondary processor and monitor results before expanding the chain
2. Match PSP strengths to your traffic -- Use PSPs with strong regional presence for your customer base
3. Review cascade analytics monthly -- Reorder your cascade chain based on actual approval rates
4. Set realistic cost weights -- Include all fees (processing, cross-border, currency conversion) for accurate routing
5. Monitor PSP health events -- Frequent health issues may indicate an integration issue or PSP degradation
6. Test with low-value transactions -- Verify your cascade chain works correctly before enabling it for all traffic

What's Next

• How Automatic Recovery Works -- Understand the full recovery pipeline
• Retry Strategies -- Learn how retry timing is optimized alongside cascading
• Integrations -- Connect additional payment processors for cascading