Multi-Gateway Failover

This page is part of the REST API Guides. Card capture happens in the frontend through the Payments Library; see the Payments Library Guides.

Prerequisites: API key and multiple Payment Gateway Accounts configured. Multi-gateway failover keeps payments running when a provider fails. You list a primary gateway and backups in the order you choose; Orchestra tries them in that order until one succeeds or the list ends. Orchestra does not choose, reorder or add gateways.

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, Orchestra tries Adyen next
Rate limiting - If a provider rejects a payment because of a rate limit, Orchestra tries the next provider
Business continuity - Problems with one provider don’t stop your payments

Where Failover Is Available

Failover is self-serve. You don’t need to contact support or change your account setup. Add a fallbackUpgs array to the request on any of these endpoints:

Charge (POST /PaymentGateway/charge)
Authorize (POST /PaymentGateway/authorize)
Payments Library sessions (POST /EWalletOperations), for CHARGE, CHARGE_AND_TOKENIZE and PREAUTH_AND_TOKENIZE operations

Each entry in fallbackUpgs names a backup Payment Gateway Account. Orchestra sends the transaction to the primary gateway first. If it fails, Orchestra tries each fallback in the order you list them. Capture, void, refund and tokenize requests do not fail over. Scheduled payments do not fail over. Each payment contract charges through its template’s payment gateway account only.

In sessions, failover applies to payments that go through a payment gateway: CardPay, Apple Pay and Google Pay. It does not apply to PayPal, BankPay or UPI, because those methods charge the payer directly without a payment gateway.

REST Example (Charge)

The primary gateway is paymentGatewayAccountName. Each fallback entry also uses paymentGatewayAccountName:

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({
    amount: 25.00,
    currency: 'USD',
    paymentGatewayAccountName: 'stripeProduction',
    fallbackUpgs: [
      { paymentGatewayAccountName: 'adyenBackup' },
      { paymentGatewayAccountName: 'worldpayTertiary' }
    ],
    card: {
      cardNumber: '@YOUR_TOKEN',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027
    }
  })
});

const result = await response.json();

curl -X POST https://api.orchestrasolutions.com/PaymentGateway/charge \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "amount": 25.00,
    "currency": "USD",
    "paymentGatewayAccountName": "stripeProduction",
    "fallbackUpgs": [
      { "paymentGatewayAccountName": "adyenBackup" },
      { "paymentGatewayAccountName": "worldpayTertiary" }
    ],
    "card": {
      "cardNumber": "@YOUR_TOKEN",
      "cardHolderName": "Jane Smith",
      "expirationMonth": 12,
      "expirationYear": 2027
    }
  }'

import requests

response = requests.post(
    'https://api.orchestrasolutions.com/PaymentGateway/charge',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'amount': 25.00,
        'currency': 'USD',
        'paymentGatewayAccountName': 'stripeProduction',
        'fallbackUpgs': [
            {'paymentGatewayAccountName': 'adyenBackup'},
            {'paymentGatewayAccountName': 'worldpayTertiary'}
        ],
        'card': {
            'cardNumber': '@YOUR_TOKEN',
            'cardHolderName': 'Jane Smith',
            'expirationMonth': 12,
            'expirationYear': 2027
        }
    }
)

result = response.json()

The same fallbackUpgs array works on POST /PaymentGateway/authorize.

Session Example (Payments Library)

In a session request, the primary gateway is paymentGatewayAccountId, and each fallback entry also uses paymentGatewayAccountId:

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'],
    allowedBrands: ['Visa', 'MasterCard', 'AMEX'],
    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"],
    "allowedBrands": ["Visa", "MasterCard", "AMEX"],
    "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'],
        'allowedBrands': ['Visa', 'MasterCard', 'AMEX'],
        'amount': 25.00,
        'currencyCode': 'USD',
        'countryCode': 'US',
        'mode': 'TEST'
    }
)

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

The `fallbackUpgs` Array

The entries have different fields on REST requests and in sessions.

REST (`charge`, `authorize`)

Field	Type	Required	Description
`paymentGatewayAccountName`	string	Yes	Name of a stored Payment Gateway Account
`paymentGatewayCertName`	string	No	Client certificate name, if the gateway requires one

Fallback entries must reference stored Payment Gateway Accounts. Only the primary gateway can use raw credentials in the paymentGatewayAccount object.

Sessions (`POST /EWalletOperations`)

Field	Type	Required	Description
`paymentGatewayAccountId`	string	Yes	ID of a stored Payment Gateway Account
`paymentGatewayCertName`	string	No	Client certificate name, if the gateway requires one
`paymentGatewayParameters`	object	No	Extra key-value parameters for this gateway. Used for `CHARGE` and `CHARGE_AND_TOKENIZE` sessions.
`pass3DSData`	boolean	No	Default `false`. Set to `true` to send the 3DS result collected in the session to this gateway, if the gateway supports 3DS

Failover Logic

On charge requests and in sessions, Orchestra works through the list like this:

Primary attempt - Orchestra sends the transaction to the primary gateway.
Check result - A Success or Accepted result ends the flow.
Check the reason code - If the primary gateway rejected the payment with one of the reason codes listed below, the flow ends.
Try fallbacks in order - Orchestra tries each fallback in the order you listed them, and stops at the first Success or Accepted result.
Final result - Orchestra returns the first successful result, or the result of the last attempt.

Orchestra only looks at the primary gateway’s rejectReasonCode to decide whether to fail over. If a fallback gateway rejects the payment, its reason code does not stop the chain: Orchestra still tries the next fallback.

The reason code rules on this page apply to charge requests and sessions. On authorize, any result other than Success or Accepted moves to the next gateway.

What Triggers Failover

Orchestra tries the next gateway when the primary attempt does not end in Success or Accepted. This includes:

Temporary and fatal gateway failures (HTTP 503 and 500 responses)
Rejections with no rejectReasonCode
Rejections with any reason code not listed below, for example DoNotHonor, InvalidCard, ProcessorDecline, ExceedsLimit, AuthenticationFailed or TechnicalError

What Doesn’t Trigger Failover

Orchestra does not fail over when the primary gateway rejects the payment with one of these rejectReasonCode values:

CardExpired
Fraud
LostOrStolenCard
InsufficientFunds

In these cases, you get the primary gateway’s result.

When a Fallback Account Can’t Be Loaded

Sessions: Orchestra checks the primary account, every fallback account and every certificate when you create the session. If one of them can’t be found, POST /EWalletOperations returns HTTP 400 and no session is created. This check does not run for TOKENIZE sessions or when none of the allowed payment methods uses a payment gateway. If a fallback account can’t be loaded later, when the payment runs, the payment fails with a FatalFailure result that describes the problem. REST: Orchestra does not check fallback accounts in advance. It loads each fallback account only when it reaches it in the list, which is after the primary gateway has failed. If it can’t load the account or certificate, the request stops and returns that error (for example HTTP 404 for an account or certificate that doesn’t exist) instead of a gateway result. Test your fallback account names before you go live.

3DS Data

REST: Every gateway in the chain gets the same request. If you send 3DS results in card.threeDSAuthentication, Orchestra sends them to the primary gateway and to every fallback. Sessions: The primary gateway gets the 3DS result collected in the session, if the gateway supports 3DS. A fallback gateway only gets it when its entry has pass3DSData: true and the gateway supports 3DS. With the default false, the fallback gets the payment without 3DS data.

Configuration Strategies

Primary + Backup

Most common setup: one primary provider, one backup for emergencies. This is a partial REST request body:

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

Geographic Routing with Failover

Combine BIN-based routing with failover on a REST charge. By the time you charge, you have the card, so you can look up the issuer country and pick the primary gateway, then add backups:

const { countryCode } = await getCardMetadata(cardBin);

const request = {
  amount: 25.00,
  currency: 'USD',
  card: {
    cardNumber: '@YOUR_TOKEN',
    cardHolderName: 'Jane Smith',
    expirationMonth: 12,
    expirationYear: 2027
  }
};

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

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(request)
});

With Client Certificates

Some gateways require client certificates. Use paymentGatewayCertName in the fallback entry. This is a partial session request body:

{
  "paymentGatewayAccountId": "stripeProduction",
  "fallbackUpgs": [
    {
      "paymentGatewayAccountId": "gatewayWithCert",
      "paymentGatewayCertName": "my-client-cert"
    }
  ]
}

On REST requests, use paymentGatewayAccountName instead of paymentGatewayAccountId.

Response

REST

The response is the result of the last attempt, and the HTTP status follows it: 200 for Success, 202 for Accepted, 409 for Rejected, 503 for TemporaryFailure and 500 for FatalFailure. Earlier failed attempts are not returned.

{
  "operationType": "Charge",
  "operationResultCode": "Success",
  "gatewayName": "Adyen",
  "gatewayReference": "txn_abc123",
  "amount": 25.00,
  "currency": "USD"
}

Sessions

Validate the result token with POST /EWalletOperations/validateResults. upgChargeResults holds the last attempt. failedUpgChargeResults lists the earlier failed attempts in order, or is null if there was only one attempt.

{
  "upgChargeResults": {
    "operationType": "Charge",
    "operationResultCode": "Success",
    "gatewayName": "Adyen",
    "gatewayReference": "txn_abc123",
    "amount": 25.00,
    "currency": "USD"
  },
  "failedUpgChargeResults": [
    {
      "operationType": "Charge",
      "operationResultCode": "TemporaryFailure",
      "gatewayName": "Stripe",
      "amount": 25.00,
      "currency": "USD"
    }
  ]
}

Which Gateway Processed the Payment

gatewayName is the payment gateway type (for example Stripe), not the name of your Payment Gateway Account. If two of your accounts use the same gateway type, use gatewayReference and your own records to tell them apart.

Send any capture, void or refund to the Payment Gateway Account that processed the payment, not to your primary account.

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

Use the mock gateways:

Create a Payment Gateway Account for NULLFailure and one for NULLSuccess.
Set the NULLFailure account as the primary gateway.
Add the NULLSuccess account as the fallback in fallbackUpgs.

NULLFailure rejects every payment without a reason code, so Orchestra fails over and the payment succeeds on NULLSuccess.

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

Where Failover Is Available

REST Example (Charge)

Session Example (Payments Library)

The `fallbackUpgs` Array

REST (`charge`, `authorize`)

Sessions (`POST /EWalletOperations`)

Failover Logic

What Triggers Failover

What Doesn’t Trigger Failover

When a Fallback Account Can’t Be Loaded

3DS Data

Configuration Strategies

Primary + Backup

Geographic Routing with Failover

With Client Certificates

Response

REST

Sessions

Which Gateway Processed the Payment

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

​Where Failover Is Available

​REST Example (Charge)

​Session Example (Payments Library)

​The fallbackUpgs Array

​REST (charge, authorize)

​Sessions (POST /EWalletOperations)

​Failover Logic

​What Triggers Failover

​What Doesn’t Trigger Failover

​When a Fallback Account Can’t Be Loaded

​3DS Data

​Configuration Strategies

​Primary + Backup

​Geographic Routing with Failover

​With Client Certificates

​Response

​REST

​Sessions

​Which Gateway Processed the Payment

​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

Where Failover Is Available

REST Example (Charge)

Session Example (Payments Library)

The `fallbackUpgs` Array

REST (`charge`, `authorize`)

Sessions (`POST /EWalletOperations`)

Failover Logic

What Triggers Failover

What Doesn’t Trigger Failover

When a Fallback Account Can’t Be Loaded

3DS Data

Configuration Strategies

Primary + Backup

Geographic Routing with Failover

With Client Certificates

Response

REST

Sessions

Which Gateway Processed the Payment

Testing Failover

Best Practices

Related