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

Gateway failover

Enable Gateway Failover in Recurly to automatically route transactions to a backup gateway when your primary gateway experiences downtime — ensuring continuous payment processing.

Gateway Failover automatically routes transactions to a backup gateway when Recurly detects a downtime or outage on the primary gateway — keeping payments processing without manual intervention.
Not included in Starter or Pro — contact Recurly Sales to upgrade
1Definition 2Key benefits 3How it works 4Enable gateway failover

Prerequisites

  • Multiple gateways configured in Recurly for each credit card type and currency you accept.

Limitations

  • Transactions tied to a specific gateway via a gateway_code always route to that gateway — failover does not apply.
  • Auth and Capture may not be compatible with Gateway Failover — captures must be completed on the same gateway as the original authorization.
  • If using Stripe with Gateway Failover, both gateways must support the same currency and card type.
  • Gateway Failover cannot be tested in sandbox mode — it is functional in production mode only.

Definition

Gateway Failover is a Recurly feature that automatically routes transactions to a backup gateway when a detected outage or downtime affects the primary gateway. It ensures continuous transaction processing and reduces the financial and operational impact of gateway outages.

Key benefits

Transaction continuity Transactions keep processing without interruption even during primary gateway outages.
Minimized financial impact Automatic rerouting reduces revenue loss from gateway downtime.
Operational resilience A backup payment path is always available, keeping your business running when primary gateways fail.

How gateway failover works

  • Recurly designates a primary and backup gateway for each credit card type and currency based on your gateway configuration. The first gateway added (or your set default gateway) is the primary; gateways added later serve as failover options, prioritized by order of addition.
  • Recurly tracks gateway error code responses on a rolling time period to detect communication errors indicating potential outages.
  • When error velocity reaches a threshold, Recurly automatically fails over to the backup gateway.
  • When Recurly detects the primary gateway has recovered, it reverts traffic back to the primary.
  • Recurring transactions are paused during a failover event to avoid failed attempts on the downed gateway. When recovery is detected, queued recurring transactions are released to the primary gateway.
  • Initial signup transactions routed to a backup gateway will have subsequent recurring transactions initiated on the primary gateway once it recovers.
  • You'll see a notification on your gateway configuration page when a failover event was detected and a secondary gateway was used.

Enable gateway failover

Turn on failover

1

Open Payment Gateways

Navigate to the Recurly gateway configuration page.

2

Enable failover

Select Enable from the Gateway Failover panel on the right.

3

Confirm

Confirm the enablement in the modal that appears.

Exclude a gateway from failover

Use this setting to prevent a gateway from participating in failover — useful when using Custom Gateway Routing to reserve a gateway for a specific purpose.

1

Open Payment Gateways

Navigate to the Recurly gateway configuration page.

2

Edit the gateway

Select Options → Edit gateway on the gateway you want to exclude.

3

Exclude from failover

Check the Exclude from gateway failover box and save.


Updated 6 days ago

Did this page help you?