Skip to main content
This page is part of the REST API Guides. Using the JavaScript library instead? See Payments Library Guides.
Prerequisites: API key and multiple Payment Gateway Accounts configured. 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 high payment availability

​
How It Works

Add a fallbackUpgs array to your charge or authorize request. Each entry specifies a backup Payment Gateway Account to try if the primary fails: 
{
  "paymentGatewayAccountName": "stripe-production",
  "fallbackUpgs": [
    { "paymentGatewayAccountName": "adyen-production" },
    { "paymentGatewayAccountName": "checkout-production" }
  ],
  "amount": 25.00,
  "currency": "USD",
  "card": { ... }
}
Orchestra sends the transaction to the primary gateway (paymentGatewayAccountName). If it fails with a recoverable error, Orchestra tries each fallback in order until one succeeds.

​
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({
    paymentGatewayAccountName: 'stripe-production',
    fallbackUpgs: [
      { paymentGatewayAccountName: 'adyen-backup' },
      { paymentGatewayAccountName: 'worldpay-tertiary' }
    ],
    amount: 25.00,
    currency: 'USD',
    card: {
      cardNumber: '4111111111111111',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027,
      cvv: '123'
    }
  })
});

const result = await response.json();

​
The fallbackUpgs Array

Each entry in the fallbackUpgs array has these fields:
FieldTypeRequiredDescription
paymentGatewayAccountNamestringYesThe name of the backup Payment Gateway Account
paymentGatewayCertNamestringNoClient certificate name, if the gateway requires one

​
Failover Logic

Orchestra tries each gateway in order:
  1. Primary attempt — Transaction sent to the gateway specified in paymentGatewayAccountName
  2. Check result — If successful, return immediately
  3. Evaluate failure — If the failure is recoverable, try the next gateway in fallbackUpgs
  4. Repeat — Continue until success or all gateways exhausted
  5. Final result — Return success from the first working gateway, or the last failure

​
What Triggers Failover

Orchestra attempts the next gateway when the primary fails with a recoverable error:
  • Gateway returns an error response (500, 503)
  • Gateway is unreachable (network timeout)
  • Gateway temporarily rejects the transaction

​
What Doesn’t Trigger Failover

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

​
Works With Charge and Authorize

The fallbackUpgs parameter is available on both operations:
  • Charge (POST /PaymentGateway/charge) — Immediate payment with failover
  • Authorize (POST /PaymentGateway/authorize) — Authorization hold with failover

​
Authorize with Failover

const response = await fetch('https://api.orchestrasolutions.com/PaymentGateway/authorize', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    paymentGatewayAccountName: 'stripe-production',
    fallbackUpgs: [
      { paymentGatewayAccountName: 'adyen-backup' }
    ],
    amount: 50.00,
    currency: 'USD',
    card: {
      cardNumber: '4111111111111111',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027,
      cvv: '123'
    }
  })
});
When using failover with authorize, the response tells you which gateway processed the transaction. Use the same gateway for the subsequent capture, void, or refund.

​
Configuration Strategies

​
Primary + Backup

Most common setup: one primary provider, one backup for emergencies. 
{
  "paymentGatewayAccountName": "stripe-production",
  "fallbackUpgs": [
    { "paymentGatewayAccountName": "adyen-backup" }
  ]
}

​
Geographic Routing with Failover

Combine BIN-based routing with failover. Use the card’s issuer country to pick the primary gateway, and add regional backups: 
const { countryCode } = await getCardMetadata(cardBin);

const request = {
  amount: 25.00,
  currency: 'USD',
  card: { ... }
};

if (countryCode === 'MA') {
  request.paymentGatewayAccountName = 'payzone-morocco';
  request.fallbackUpgs = [
    { paymentGatewayAccountName: 'stripe-global' }
  ];
} else {
  request.paymentGatewayAccountName = 'stripe-global';
  request.fallbackUpgs = [
    { paymentGatewayAccountName: 'adyen-global' },
    { paymentGatewayAccountName: 'checkout-global' }
  ];
}

​
With Client Certificates

Some gateways require client certificates. Use paymentGatewayCertName in the fallback entry: 
{
  "paymentGatewayAccountName": "stripe-production",
  "fallbackUpgs": [
    {
      "paymentGatewayAccountName": "gateway-with-cert",
      "paymentGatewayCertName": "my-client-cert"
    }
  ]
}

​
Response

The response includes which gateway processed the transaction. Use the gatewayName field to identify which provider succeeded: 
{
  "operationType": "Charge",
  "operationResultCode": "Success",
  "gatewayName": "Adyen",
  "gatewayReference": "txn_abc123",
  "amount": 25.00,
  "currency": "USD"
}
Track which gateway succeeded to help with:
  • Cost analysis per provider
  • Performance monitoring
  • Ensuring subsequent operations (capture, void, refund) go to the correct gateway

​
Testing Failover

Test your failover configuration using mock gateways. See Mock PSPs for setup details.

​
Best Practices

Order by Preference

List fallback gateways in order of preference — lowest cost or best performance first.

Monitor Usage

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

Test Regularly

Verify failover works by simulating primary gateway failures in sandbox.

Geographic Alignment

Use providers with strong presence in your target markets as primary for those regions.

How Orchestra Works

Understanding Orchestra’s architecture

Payment Gateway Accounts

Configure multiple providers

Charge Payments

Basic charge operation

Card Metadata Lookup

Get card issuer country for BIN-based routing