Skip to main content

Provider Failover

Provider Failover allows SolydFlow to route a payment attempt to an alternative, healthy payment gateway when your primary provider is experiencing degraded performance or an unexpected outage.

[1. Primary Rail Times Out] ➔ [2. Verify Previous Intent] ➔ [3. Confirm Unbilled] ➔ [4. Safe Failover to Backup Rail]

The most important rule in payment infrastructure is safety. A gateway timeout does not mean the payment failed—the bank may have already debited the user's card. SolydFlow verifies the previous attempt before triggering a fallback rail.

Blind Failover vs. SolydFlow Safe Failover​

Failover ApproachHow It Handles a TimeoutRisk LevelThe Outcome
❌ Naive / Blind FailoverPaystack times out (504) ➔ Immediately charge via Flutterwave.Extreme RiskCustomer debited twice. Chargeback filed.
✅ SolydFlow Safe FailoverPaystack times out (504) ➔ Hold intent ➔ Query Paystack verify API ➔ Only switch to Flutterwave if confirmed uncharged.Zero RiskCustomer billed once; subscription unlocked cleanly.

Master Failover Decision Matrix​

Gateway ConditionWhat HappenedIs Failover Safe?SolydFlow Action
Pre-Flight OutagePrimary gateway returns 503 Service Unavailable before payment starts.✅ Yes (Immediate)Routes checkout intent directly to eligible backup rail.
Definitive DeclinePrimary gateway confirms Card Expired or Insufficient Balance.✅ Yes (Conditional)Prompts user to select an alternative payment method or card.
Gateway Timeout (504)Socket drops mid-checkout; gateway status unknown.⚠️ Hold & VerifyConsensus Engine queries primary gateway API before allowing fallback.
Settled at PrimaryPrimary gateway confirms payment cleared after initial timeout.❌ ForbiddenStops failover immediately. Unlocks entitlement via primary rail.

The 2 Operational Failover Modes​

1. Pre-Flight Failover (Before Checkout Initiates)​

If SolydFlow detects that your primary provider is experiencing high latency or downtime:

  • A Nigerian user attempting to pay in NGN is seamlessly served a Monnify Virtual Account instead of an unresponsive card modal.
  • The customer experiences zero checkout errors or broken spinners.

2. Mid-Flight Safe Failover (During an Active Session)​

If a provider hangs after the user submits their payment details:

[User Submits Card on Paystack] ➔ [Paystack Times Out (504)] ➔ [SolydFlow Queries GET /verify] ➔ [Paystack: "No Charge Recorded"] ➔ [Prompts Fallback to Monnify / Flutterwave]

Because SolydFlow confirms with Paystack that no money was deducted, failing over to a backup provider is 100% safe against double-debiting.

Real-World Multi-Rail Failover Paths​

To enable automated failover, ensure backup credentials are saved in your API Credentials Vault:

┌───────────────────────────────────────┬───────────────────────────────┬───────────────────────────────┐
│ Market & Currency                     │ Primary Payment Rail          │ Automated Failover Rail       │
├───────────────────────────────────────┼───────────────────────────────┼───────────────────────────────┤
│ 🇳🇬 Nigeria (NGN)                      │ Paystack (Cards / USSD)       │ Monnify (Virtual Accounts)    │
├───────────────────────────────────────┼───────────────────────────────┼───────────────────────────────┤
│ 🇰🇪 Kenya (KES)                        │ M-Pesa STK Push (Daraja)      │ Paystack / Flutterwave        │
├───────────────────────────────────────┼───────────────────────────────┼───────────────────────────────┤
│ 🇬🇭 Ghana (GHS)                        │ Flutterwave Mobile Money      │ Paystack Mobile Money         │
├───────────────────────────────────────┼───────────────────────────────┼───────────────────────────────┤
│ 🌍 Global (USD / EUR)                 │ Stripe Credit Cards           │ Paystack International Cards  │
└───────────────────────────────────────┴───────────────────────────────┴───────────────────────────────┘

Failover Audit Trail in the Ledger​

When a transaction successfully fails over to a secondary provider, the transition is permanently recorded in your Immutable Ledger:

Ledger Failover Entry (JSON)
{
  "transaction_id": "txn_01J8K9B2D7E4F1A0C5E8",
  "attempts": [
    {
      "attempt_number": 1,
      "provider": "paystack",
      "status": "GATEWAY_TIMEOUT",
      "verified_uncharged": true
    },
    {
      "attempt_number": 2,
      "provider": "monnify",
      "status": "SETTLED_CONSENSUS",
      "reference": "ref_mnf_991823746"
    }
  ],
  "final_state": "SETTLED_CONSENSUS",
  "entitlement_granted": "pro_access"
}