Skip to main content
Multi-gateway failover is Orchestra’s core value proposition: if one payment provider fails or is unavailable, Orchestra automatically tries the next provider in your list until one succeeds.

​
Why Use Multi-Gateway Failover

Without Orchestra, a provider outage means lost transactions. With multi-gateway failover, your payment flow stays resilient:
  • Provider downtime - If Stripe is down, transactions automatically route to Adyen
  • Regional issues - Network problems in one region don’t affect your entire payment flow
  • Rate limiting - Exceed limits on one provider, overflow to another
  • Business continuity - Maintain 99.9%+ payment availability

​
How It Works

Instead of specifying a single paymentGatewayAccountName, use the plural paymentGatewayAccountNames with an array of gateway account names: 
{
  "paymentGatewayAccountNames": [
    "stripe-production",      // Try first
    "adyen-production",       // Try if Stripe fails
    "checkout-production"     // Try if Adyen fails
  ],
  "amount": 25.00,
  "currency": "USD",
  "card": { ... }
}
Orchestra attempts each gateway sequentially until one succeeds. The first successful response is returned to you.

​
Basic Example

const response = await fetch('https://api.orchestrasolutions.com/PaymentGateway/charge', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    paymentGatewayAccountNames: [
      'stripe-production',
      'adyen-backup',
      'worldpay-tertiary'
    ],
    amount: 25.00,
    currency: 'USD',
    card: {
      cardNumber: '4111111111111111',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027,
      cvv: '123'
    }
  })
});

const result = await response.json();
Use paymentGatewayAccountNames (plural) for failover. The singular paymentGatewayAccountName routes to a single provider without failover.

​
Failover Logic

Orchestra tries each gateway in order:
  1. First attempt - Transaction sent to first gateway in array
  2. Check result - If successful, return immediately
  3. On failure - Try next gateway in array
  4. Repeat - Continue until success or all gateways exhausted
  5. Final result - Return success from first working gateway, or failure if all fail

​
What Triggers Failover

Orchestra attempts the next gateway when:
  • Gateway returns an error response (500, 503)
  • Gateway is unreachable (network timeout)
  • Gateway explicitly rejects the transaction
  • Gateway rate limit exceeded

​
What Doesn’t Trigger Failover

Orchestra does NOT fail over when:
  • Card is declined by the issuing bank (legitimate decline)
  • Insufficient funds
  • Invalid card number or CVV
  • Card expired
These are payment failures, not gateway failures. The card would be declined on any provider.

​
Configuration Strategies

​
Primary + Backup

Most common setup: one primary provider, one backup for emergencies. 
{
  "paymentGatewayAccountNames": [
    "stripe-production",
    "stripe-backup"  // Different Stripe account or Adyen
  ]
}

​
Geographic Routing

Different providers for different regions: 
// Europe transactions
{
  "paymentGatewayAccountNames": [
    "adyen-europe",
    "worldpay-europe",
    "stripe-global"
  ]
}

// US transactions
{
  "paymentGatewayAccountNames": [
    "stripe-us",
    "authorize-net-us",
    "adyen-global"
  ]
}

​
Load Distribution

Distribute load across multiple providers for high-volume scenarios: 
// Randomly select primary, with backups
const gateways = [
  ['stripe-1', 'adyen-backup'],
  ['stripe-2', 'adyen-backup'],
  ['adyen-1', 'stripe-backup']
][Math.floor(Math.random() * 3)];

{
  "paymentGatewayAccountNames": gateways
}

​
Works With All Operations

Multi-gateway failover works with:
  • Charge - Immediate payment capture
  • Authorize - Hold funds for later capture
  • Tokenize - Generate gateway tokens
Simply use paymentGatewayAccountNames instead of paymentGatewayAccountName in any request.

​
Response Details

The response includes which gateway succeeded: 
{
  "success": true,
  "transactionId": "txn_abc123",
  "paymentGatewayAccountName": "adyen-backup",  // Shows which gateway succeeded
  "gatewayResponse": {
    "code": "approved",
    "message": "Transaction approved"
  }
}
Use paymentGatewayAccountName in the response to track which provider processed the transaction. This helps with:
  • Cost analysis per provider
  • Performance monitoring
  • Debugging routing issues

​
Testing Failover

Test your failover configuration using mock gateways: 
{
  "paymentGatewayAccountNames": [
    "test-failure",   // Will fail
    "test-failure",   // Will fail
    "test-success"    // Will succeed
  ],
  "amount": 10.00,
  "currency": "USD",
  "card": { ... }
}
The transaction will fail on the first two attempts, then succeed on the third. Check the response to confirm "paymentGatewayAccountName": "test-success". See Mock PSPs for testing strategies.

​
Best Practices

Order by Preference

List gateways in order of preference. Lowest cost or best performance first.

Monitor Usage

Track which gateways are being used. High failover rates indicate primary issues.

Test Regularly

Verify failover works by simulating primary gateway failures.

Geographic Alignment

Use providers with strong presence in your target markets.

How Orchestra Works

Understanding Orchestra’s architecture

Payment Gateway Accounts

Configure multiple providers

Charge Payments

Basic charge operation

Mock PSPs

Test failover with mock gateways