HomeProduct DocsAPI ReferenceChangelog
RecurlyAPI GuidesRecurly.jsWebhooksAPI ReferenceSupportBook demo
Product Docs
RecurlyAPI GuidesRecurly.jsWebhooksAPI ReferenceSupportBook demo

Multiple gateway configuration

Configure multiple payment gateways in Recurly to support diverse currencies, card types, and payment methods — with gateway hierarchy, default settings, and failover.

Multiple gateway configuration lets you connect several payment gateways to your Recurly account to support different currencies, card types, and payment methods — with control over routing hierarchy, default gateways, and failover behavior.
Available on all Recurly plans
1Definition 2Key benefits 3Key details 4Setup

Prerequisites

  • An active Recurly account.
  • Access to the gateway providers you want to connect.
  • An understanding of your business's transaction routing needs.

Limitations

  • By default, transactions route to the first gateway added that supports the transaction's currency and card type — unless custom routing or default settings are configured.
  • The gateway hierarchy must be correctly understood and configured to ensure transactions process as intended.

Definition

Multiple gateway configuration lets Recurly merchants connect several payment gateways to accept diverse payment types, process transactions in multiple currencies, and maintain a backup gateway in case a primary gateway experiences downtime.

Key benefits

Broad payment support Support a wide range of payment methods and currencies across multiple gateway providers.
Optimized transaction routing Prioritize which gateway processes specific transactions based on card type, currency, or custom rules.
Business continuity Gateway Failover automatically reroutes payments to a secondary gateway if the primary becomes unavailable.
Custom routing Define gateway use based on your business logic using Custom Gateway Routing.
Centralized management View and manage all gateway configurations from a single dashboard.

Key details

Gateway support

Recurly supports multiple gateway configurations to cover a range of currencies, card types, and payment methods — including credit cards, external gateway tokens, Amazon Pay, PayPal, Apple Pay, ACH, and more.

Gateway hierarchy

When multiple gateways are configured, Recurly routes transactions to the first gateway on the list that supports the transaction's card type and currency. Beyond this default, Recurly applies the following routing hierarchy:

  1. Transactions with a gateway token (e.g., Vantiv tokens, Braintree tokens)
  2. Transactions referencing a gateway_code (Custom Gateway Routing)
  3. Non-credit card transactions (PayPal, Amazon Pay, Adyen HPP, etc.)
  4. The default gateway for credit card transactions
  5. The non-default credit card gateway, prioritizing the one added earliest

Custom gateway routing

For precise control over which gateway handles a transaction, use Recurly's Custom Gateway Routing.

Default gateway

You can set a default gateway for credit card transactions. The default gateway takes precedence when it's compatible with the transaction's card type and currency and no specific gateway_code has been assigned via Custom Gateway Routing.

Gateway failover

Gateway Failover automatically reroutes transactions to a secondary gateway if the primary becomes unavailable. When the primary gateway recovers, Recurly resumes routing new transactions to it.

Setting up multiple gateways

Add a gateway

1

Open Payment Gateways

In Recurly, go to Configuration → Payment Gateways.

2

Add a new gateway

Click Payment Gateway Actions → Add Payment Gateway and select your preferred provider from the table of brand icons.

3

Enter credentials

Input the required credentials or API keys for the chosen provider, then confirm and save.

4

Repeat for additional gateways

To add more gateways, repeat the process with different providers as needed.

Set a default gateway

1

Open Default Gateways

In the Payment Gateways section, find Default Gateways in the sidebar.

2

Edit defaults

Click Edit Defaults, assign a default gateway for each payment method in the window, then confirm and save.

Enable gateway failover

1

Open Gateway Failover settings

In the Payment Gateways section, find Gateway Failover in the sidebar.

2

Enable failover

Toggle failover to Enabled or Disabled as needed. Note that setting specific Primary and Backup gateways via a dropdown is not available on this page.

Tip After configuration, run a few test transactions to confirm routing works as expected based on your hierarchy and default settings. Revisit and adjust settings at any time as your needs evolve.

Updated 7 days ago

Did this page help you?