Gateway failover

Ensure seamless transaction processing during primary gateway downtimes with Recurly's Gateway Failover feature, which automatically routes transactions to a backup gateway and reverts back post resolution.


Required plan

This feature is only available to customers on the Professional and/or Elite subscription plan. To request to upgrade to this plan, please reach out to your Recurly account manager or [email protected] for more details.


  • Merchants should have multiple gateways configured for each credit card type and currency they accept.
  • Merchants should be on the Recurly's Professional plan to access this feature.


  • Transactions tied to a specific gateway via a gateway_code will always route to the specified gateway, despite a failover scenario.
  • The Auth and Capture feature may not be compatible with Gateway Failover as captures need to be completed on the same gateway as the original authorization.
  • If using Stripe with Gateway Failover, ensure that both gateways support the same currency and card type.
  • Testing Gateway Failover in sandbox mode is not supported; the feature is functional only in production mode.


Gateway Failover is a feature designed to provide a safety net for merchants by automatically routing transactions to a backup gateway whenever there's a detected outage or downtime with the primary gateway. This not only ensures the continuous processing of transactions but also significantly diminishes the financial and operational impact of gateway outages.

Key benefits

  • Continuity in transactions processing: Ensures transactions are processed without interruption even during primary gateway outages.
  • Minimized financial impact: By rerouting transactions, financial losses due to gateway outages are substantially reduced.
  • Operational resilience: Enhances operational resilience by providing a backup plan for payment processing, thereby maintaining a good customer experience.

Enable gateway failover

  1. Navigate to the Recurly gateway configuration page and select "Enable" from the Gateway Failover modal on the right.

Enable Gateway Failover

  1. Confirm feature enablement on the modal that appears.

Confirmation Modal

  1. A banner indicating successful feature enablement will be displayed on the gateway configuration page.

Confirmation Banner

Exclude a Gateway from Failover

TO EXCLUDE A GATEWAY, follow these steps:

  1. Go to the Recurly gateway configuration page.
  2. Select (1) Options > (2) Edit Gateway on the desired gateway entry to edit.

Exclude Step 1

  1. Check the box for: "Exclude from Gateway Failover."

Exclude Step 2

This exclusion is crucial for merchants utilizing Custom Gateway Routing who wish to prevent failover transactions from being routed to a gateway designated for specific purposes.

Gateway Failover implementation details

  • Merchants will be able to enable Gateway Failover from their gateway configuration page, by designating a primary and backup gateway for each credit card type and currency. Recurly will default to the first gateway added or set default gateway for the specific card type and currency. Gateway(s) added to the site after will then be used for failover scenarios (prioritizing the earlier addition(s) first).
  • Recurly will track gateway error code responses to detect potential outages or downtime, specifically targeting communication error type responses. This will be calculated on a rolling time period.
  • When gateway errors are detected and reach a certain velocity, Recurly will failover to the backup gateway, routing transactions to that gateway.
  • The calculation will also be able to inform Recurly when the primary gateway has recovered, so Recurly can revert back to the primary gateway.
  • Initial signup transactions that were routed to a backup gateway will be initiated as recurring transactions on the primary gateway, even if they were originally routed to the backup gateway.
  • Merchants will be notified on their gateway configuration page that a gateway failover scenario was detected and a secondary gateway was used.
  • Recurring transactions will be paused, so that these transactions are not attempted on the gateway that is down. When Recurly identifies that the gateway has recovered, Recurly will release the queue of recurring transactions to be routed to the primary gateway.