Gateway Failover: Designing for Provider Outages

class GatewayCircuitBreaker {
  constructor({ primaryGateway, fallbackGateway, failureThreshold = 5, resetTimeoutMs = 300000 }) {
    this.primary = primaryGateway;
    this.fallback = fallbackGateway;
    this.failures = 0;
    this.failureThreshold = failureThreshold;
    this.state = 'closed'; // closed = primary active, open = using fallback
    this.resetTimeout = resetTimeoutMs;
    this.lastFailureTime = null;

    // Health check every 30 seconds
    setInterval(() => this.healthCheck(), 30000);
  }

  async healthCheck() {
    if (this.state !== 'open') return;
    // Check if timeout has elapsed since last failure
    if (Date.now() - this.lastFailureTime > this.resetTimeout) {
      try {
        await this.primary.ping(); // implement a lightweight health check
        this.reset(); // primary healthy — close the breaker
        console.log('Circuit breaker reset: primary gateway restored');
      } catch {
        this.lastFailureTime = Date.now(); // extend timeout
      }
    }
  }

  async initializePayment(params) {
    var gateway = this.state === 'open' ? this.fallback : this.primary;

    try {
      var result = await gateway.initialize(params);
      if (this.state !== 'open') this.failures = 0; // reset on success
      return result;
    } catch (err) {
      if (this.state !== 'open') {
        this.failures++;
        this.lastFailureTime = Date.now();
        if (this.failures >= this.failureThreshold) {
          this.state = 'open';
          console.error('Circuit breaker opened: switching to fallback gateway');
        }
      }
      throw err; // re-throw so caller handles
    }
  }

  reset() {
    this.state = 'closed';
    this.failures = 0;
  }
}

// Usage
var payments = new GatewayCircuitBreaker({
  primaryGateway: new PaystackGateway(process.env.PAYSTACK_SECRET_KEY),
  fallbackGateway: new FlutterwaveGateway(process.env.FLUTTERWAVE_SECRET_KEY),
  failureThreshold: 5,
  resetTimeoutMs: 5 * 60 * 1000, // 5 minutes
});

See building a payment provider abstraction layer for the prerequisite design that makes failover possible.

Sign up for the McTaba newsletter