> ## Documentation Index
> Fetch the complete documentation index at: https://developers.orchestrasolutions.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Multi-Gateway Failover
> Configure automatic failover across multiple payment providers.
This page is part of the **REST API Guides**. Using the JavaScript library instead? See [Payments Library Guides](/guides/library/setup).
**Prerequisites:** [API key](/getting-started/generate-api-key) and multiple [Payment Gateway Accounts](/getting-started/add-payment-provider) 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:
```json theme={null}
{
"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.
Email **[support@orchestrasolutions.com](mailto:support@orchestrasolutions.com)** to enable multi-gateway failover for charge and authorize requests.
## Basic Example
```javascript Node.js theme={null}
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);
```
```bash cURL theme={null}
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"
}'
```
```python Python theme={null}
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:
1. **Primary attempt** - Transaction sent to the gateway specified in `paymentGatewayAccountId`
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.
## 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`)
Email **[support@orchestrasolutions.com](mailto: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.
```json theme={null}
{
"paymentGatewayAccountId": "stripeProduction",
"fallbackUpgs": [
{ "paymentGatewayAccountId": "adyenBackup" }
]
}
```
### Geographic Routing with Failover
Combine [BIN-based routing](/guides/rest-api/utilities/card-tools/metadata-lookup) with failover. Use the card's issuer country to pick the primary gateway, and add regional backups:
```javascript theme={null}
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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](/guides/utilities/mock-psps) for setup details.
## Best Practices
List fallback gateways in order of preference - lowest cost or best performance first.
Track which gateways are being used. High failover rates indicate issues with the primary.
Verify failover works by simulating primary gateway failures in sandbox.
Use providers with strong presence in your target markets as primary for those regions.
## Related
Understanding Orchestra's architecture
Configure multiple providers
Basic charge operation
Get card issuer country for BIN-based routing