The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

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.

If you would like to have this feature enabled, please reach out to Recurly support.

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 resolve. This significantly reduces the impact to the business when its gateway experiences an outage.

Merchant Benefit

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

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 https://recurly.com/gateways/

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 also 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. Contact Recurly Support to have the Gateway Failover feature enabled for your site.
  2. 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.

Limitations

  1. Merchants using Custom Gateway Routing functionality, who specify a gateway_code for each transaction will not be able to utilize Recurly's Gateway Failover functionality. This is due to the hierarchy that Recurly will prioritize transaction requests using gateway_code and give priority to a failover scenario.
  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.

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.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.