Failover is SwitchFlow’s core mechanic: when your priority-1 gateway fails in a retryable way, the same payment is re-attempted on your next-priority gateway inside the same customer interaction. The customer’s checkout shows one continuous loading state — a failover is indistinguishable from a first-attempt success.

​
Failure classification

Every gateway response is normalized into one of three classes:
ClassExamplesFailover?
Fraud-class (terminal)stolen card, lost card, fraud suspected, invalid cardNever — surfaced to the customer immediately
Hard decline (retryable)do_not_honor, card_declined, insufficient_fundsYes, if hardDeclines trigger is on
Infrastructureper-attempt timeout, gateway 5xx, network errorYes, if timeouts / gatewayErrors triggers are on

​
Latency budget

Failover only helps if it is fast enough that the customer never notices:
  • p95 target: ≤ 2,500 ms for a two-attempt checkout (attempt 1 + failover decision + attempt 2).
  • Absolute ceiling: 4,500 ms. The moment total processing time would breach the ceiling, the engine halts all retries — no zombie attempts.

​
Degradation: when everything is down

If all configured gateways fail with timeouts/5xx in one checkout (a double blackout), SwitchFlow does not show your customer an error page. Instead the widget receives: 
{ "action": "RETRY_ALTERNATIVE_METHOD" }
and swaps the card form for your configured alternative payment method (for example, a PayPal button) — the customer sees a fallback option, not a failure. You receive a payment.failed webhook with reason: "gateway_blackout" so your systems know no capture happened. See widget reference for configuring the fallback label and behavior.

​
What you see afterwards

Every payment carries a full attempt trail — gateway, outcome, normalized decline code, decline class, and latency per attempt — available on GET /payment-sessions/{id}, in the webhook payload, and in the dashboard’s failover event log.