Gateway failover

Gateway Failover will provide merchants with redundancy in their gateway configuration. Recurly will automatically route transactions to a backup gateway when their primary gateway is unavailable due to an issue or outage.

Purpose Statement

Recurly’s Gateway Failover functionality will give merchants gateway redundancy by auto-detecting gateway outages or downtime and then routing transactions to a backup gateway. Recurly automatically reverts back to the primary gateway when the issue has been resolved. This significantly reduces the impact to the business when its gateway experiences an outage.

Merchant Benefit

Learn more about the importance of multiple payment gateways in our blog.

Merchants gain peace of mind that in the event of a gateway outage, knowing that transactions will be routed to a backup gateway. Watch a video to learn more.

Merchant Prerequisites

Merchants will need to have multiple gateways set up for each credit card type and currency they accept. If there is not a backup gateway for each card type and currency, those transactions will not be able to failover, but this does not limit other transactions from being part of failover.

Need help choosing a gateway? See the Recurly blog post article for help evaluating a new gateway. Recurly offers many gateway integrations, and the ability to sign up for a merchant account easily from within Recurly for gateways such as CardConnect, which offers Recurly exclusive pricing. To see the gateways Recurly supports in your country, please visit

Gateway Failover is available on Recurly's Pro and Enterprise plans.

Supported functionality

  • One-time transactions.
  • Initial transaction (of subsequent recurring transactions).
  • Hybrid transactions of initial subscription sign ups with one-time or add on products.

Supported gateways

All credit card gateways will be supported for credit card transactions. Alternative payment methods such as PayPal and Amazon Pay are not supported for failover, as they are a single source payments provider. Apple Pay transactions are supported, with backup gateways for Apple Pay via a Stripe and Vantiv combination.

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.

Enable Gateway Failover

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

  1. Confirm feature enablement on the modal that appears.

  1. The gateway configuration page will reflect a banner showing successful feature enablement.

Exclude a gateway from Failover

TO EXCLUDE A GATEWAY merchants will need to complete the following steps:

  1. Go into the Recurly gateway configuration page.
  2. Edit each gateway that you wish to exclude from gateway failover by selecting (1) Options > (2) Edit Gateway on the gateway entry.

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

*This step is important for merchants who are using Custom Gateway Routing and do not wish for any failover transactions to be routed to a gateway used for specific purposes.


  1. Subscriptions or invoices that are submitted via API with a gateway_code (learn more about Custom Gateway Routing) will always route to the specified gateway, even if the gateway is in failover. Subscriptions or invoices that were previously created with a gateway_code assigned will be attempted when the gateway is not in failover, and is gateway status is active.
  2. Merchants using Auth and Capture feature will not be able to take advantage of Gateway Failover. This is due to the fact that the capture (or cancel) needs to be completed on the same gateway as the original authorization. This may not be the case in a failover scenario, as the initial authorization may have been run on the backup gateway. Additionally, not all gateways support auth and capture.
  3. If you use Stripe with Gateway Failover, you must make sure the two gateways match the same currency and card type support.
  4. Testing Gateway Failover in sandbox is currently not supported as this feature is only functional with Recurly sites in production mode.