Multi-Gateway Failover

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

Self-serve failover is available today on the eWallet checkout session endpoint (POST /EWalletOperations). Add a fallbackUpgs array to the session request; each entry specifies a backup Payment Gateway Account to try if the primary fails:

{
  "operation": "CHARGE",
  "paymentGatewayAccountId": "stripeProduction",
  "fallbackUpgs": [
    { "paymentGatewayAccountId": "adyenProduction" },
    { "paymentGatewayAccountId": "checkoutProduction" }
  ],
  "amount": 25.00,
  "currencyCode": "USD",
  "countryCode": "US"
}

Orchestra sends the transaction to the primary gateway (paymentGatewayAccountId). If it fails with a recoverable error, Orchestra tries each fallback in order until one succeeds. For direct charge and authorize requests, failover isn’t a field you pass in the request body: it’s configured on your Payment Gateway Account setup.

Contact Support

Email support@orchestrasolutions.com to enable multi-gateway failover for charge and authorize requests.

Basic Example

const response = await fetch('https://api.orchestrasolutions.com/EWalletOperations', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    operation: 'CHARGE',
    paymentGatewayAccountId: 'stripeProduction',
    fallbackUpgs: [
      { paymentGatewayAccountId: 'adyenBackup' },
      { paymentGatewayAccountId: 'worldpayTertiary' }
    ],
    allowedeWalletAccountIds: ['card-payments'],
    amount: 25.00,
    currencyCode: 'USD',
    countryCode: 'US',
    mode: 'TEST'
  })
});

const data = await response.json();
console.log('Session token:', data.token);

curl -X POST https://api.orchestrasolutions.com/EWalletOperations \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "operation": "CHARGE",
    "paymentGatewayAccountId": "stripeProduction",
    "fallbackUpgs": [
      { "paymentGatewayAccountId": "adyenBackup" },
      { "paymentGatewayAccountId": "worldpayTertiary" }
    ],
    "allowedeWalletAccountIds": ["card-payments"],
    "amount": 25.00,
    "currencyCode": "USD",
    "countryCode": "US",
    "mode": "TEST"
  }'

import requests

response = requests.post(
    'https://api.orchestrasolutions.com/EWalletOperations',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'operation': 'CHARGE',
        'paymentGatewayAccountId': 'stripeProduction',
        'fallbackUpgs': [
            {'paymentGatewayAccountId': 'adyenBackup'},
            {'paymentGatewayAccountId': 'worldpayTertiary'}
        ],
        'allowedeWalletAccountIds': ['card-payments'],
        'amount': 25.00,
        'currencyCode': 'USD',
        'countryCode': 'US',
        'mode': 'TEST'
    }
)

data = response.json()
print('Session token:', data['token'])

The `fallbackUpgs` Array

Each entry in the fallbackUpgs array has these fields:

Field	Type	Required	Description
`paymentGatewayAccountId`	string	Yes	The ID of the backup Payment Gateway Account
`paymentGatewayCertName`	string	No	Client certificate name, if the gateway requires one
`pass3DSData`	boolean	No	Whether to pass through 3DS authentication data collected in this session

Failover Logic

Orchestra tries each gateway in order:

Primary attempt - Transaction sent to the gateway specified in paymentGatewayAccountId
Check result - If successful, return immediately
Evaluate failure - If the failure is recoverable, try the next gateway in fallbackUpgs
Repeat - Continue until success or all gateways exhausted
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.

Availability

Self-serve failover via fallbackUpgs is available today on:

eWallet checkout sessions (POST /EWalletOperations) - add fallbackUpgs to the session request, as shown above.

For direct payment operations, failover is configured with Orchestra support rather than a request field:

Charge (POST /PaymentGateway/charge)
Authorize (POST /PaymentGateway/authorize)

Contact Support

Email support@orchestrasolutions.com to enable multi-gateway failover for charge and authorize requests.

When failover triggers, the response tells you which gateway processed the transaction. Use the same gateway for any subsequent capture, void, or refund.

Configuration Strategies

Primary + Backup

Most common setup: one primary provider, one backup for emergencies.

{
  "paymentGatewayAccountId": "stripeProduction",
  "fallbackUpgs": [
    { "paymentGatewayAccountId": "adyenBackup" }
  ]
}

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 = {
  operation: 'CHARGE',
  amount: 25.00,
  currencyCode: 'USD',
  countryCode
};

if (countryCode === 'MA') {
  request.paymentGatewayAccountId = 'payzoneMorocco';
  request.fallbackUpgs = [
    { paymentGatewayAccountId: 'stripeGlobal' }
  ];
} else {
  request.paymentGatewayAccountId = 'stripeGlobal';
  request.fallbackUpgs = [
    { paymentGatewayAccountId: 'adyenGlobal' },
    { paymentGatewayAccountId: 'checkoutGlobal' }
  ];
}

With Client Certificates

Some gateways require client certificates. Use paymentGatewayCertName in the fallback entry:

{
  "paymentGatewayAccountId": "stripeProduction",
  "fallbackUpgs": [
    {
      "paymentGatewayAccountId": "gatewayWithCert",
      "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

Start Here

Beyond the Quickstart

Concepts

Orchestra Payments Library Guides

Orchestra REST API Guides

Utilities

Merchant Account Setup

Support

Changelog

Why Use Multi-Gateway Failover

How It Works

Contact Support

Basic Example

The `fallbackUpgs` Array

Failover Logic

What Triggers Failover

What Doesn’t Trigger Failover

Availability

Contact Support

Configuration Strategies

Primary + Backup

Geographic Routing with Failover

With Client Certificates

Response

Testing Failover

Best Practices

Order by Preference

Monitor Usage

Test Regularly

Geographic Alignment

How Orchestra Works

Payment Gateway Accounts

Charge Payments

Card Metadata Lookup

​Why Use Multi-Gateway Failover

​How It Works

Contact Support

​Basic Example

​The fallbackUpgs Array

​Failover Logic

​What Triggers Failover

​What Doesn’t Trigger Failover

​Availability

Contact Support

​Configuration Strategies

​Primary + Backup

​Geographic Routing with Failover

​With Client Certificates

​Response

​Testing Failover

​Best Practices

Order by Preference

Monitor Usage

Test Regularly

Geographic Alignment

​Related

How Orchestra Works

Payment Gateway Accounts

Charge Payments

Card Metadata Lookup

Why Use Multi-Gateway Failover

How It Works

Basic Example

The `fallbackUpgs` Array

Failover Logic

What Triggers Failover

What Doesn’t Trigger Failover

Availability

Configuration Strategies

Primary + Backup

Geographic Routing with Failover

With Client Certificates

Response

Testing Failover

Best Practices

Related