Prerequisites

• Multiple gateways configured in Recurly for the payment type you want to route (e.g., credit cards).

Limitations

• Card on File NTIDs and TLIDs — Depending on the gateway, Card on File NTID and TLID data is packaged in different formats. In most cases the raw network transaction ID / transaction link ID is accepted and recurring transactions process normally. In rare cases, when incompatible gateways are used for failover, reverting to the original gateway is not possible.
• Multiple subscriptions in a single request — When passing gateway_code for multiple subscriptions within a single request, routing to different gateways per subscription is not honoured.
• Custom failover routing — When using a backup_gateway_code, this applies only to the signup transaction. Backup gateways cannot be applied directly to a subscription. Backup gateway code is only available via the V3 API.
• Stripe card brand awareness — Card brands for Stripe gateways are configured in the Stripe dashboard, not in Recurly. Recurly is not aware of which card brands your Stripe account supports. If certain card brands aren't supported by Stripe but are by other gateways, specify a gateway_code to route those transactions to the correct gateway. Review your Stripe configuration in the merchant portal to confirm your routing setup.

Definition

Key benefits

Key details

Supported transactions and payment methods

Supported transaction types:

• One-time transactions
• Initial subscription transactions
• Recurring subscription renewals (gateway_code only)

Supported payment methods:

• Credit cards
• PayPal (excluding PayPal through Braintree)
• Amazon Pay

Supported API versions:

• V2 and V3 endpoints support the gateway_code parameter.
• V3 endpoints support the backup_gateway_code parameter.

Placement controls behavior

When using a custom gateway code, its placement within your API request matters for the behavior you wish to see.

• Placement of the gateway_code or backup_gateway_code in the billing info object will use that code for the transaction in progress only. If the transaction is a subscription signup, the gateway code / backup code used in the signup does not persist to the renewal.
• Placement of the gateway_code as a top level parameter controls Renewals only.

Additional use cases

• Passing gateway_code in an API request routes the transaction to the associated gateway. If the code is absent or doesn't match a configured gateway, the transaction routes to the default gateway — with certain mismatches causing a transaction failure.
• The gateway_code does not persist for recurring transactions unless used in the correct placement via API, routing all subsequent subscription renewals to the default gateway unless set via API.
• Update the gateway_code via a PUT request to v2/subscriptions/:uuid/notes or v3 /subscriptions/{subscription_id}. Clear it with an empty tag to revert to standard routing logic.
• Retrieve the gateway_code for a subscription via GET requests to /subscriptions.
• Modify the gateway_code at the invoice level using v2/invoices/<uuid> or v3 /invoices/<invoice_id>.
• Unique Recurly gateway instances are required to route to different gateways — either via a unique Merchant Account ID / MID or by using a different gateway provider entirely.
• If the gateway_code is incompatible with the payment method on a transaction, the transaction defaults to the original gateway for that method.
• Applying gateway codes to all subscriptions within a single API request is supported.
• For aggregate invoices: if all subscriptions share the same gateway_code, that gateway is used. If codes differ or are unspecified, the default gateway is used.
• The gateway_code is visible on the transaction detail page, included in the Transaction Export, and appears in webhooks.

Backup Gateway Code behavior

• If the backup_gateway_code is incompatible with the payment method on a transaction, the transaction will fail.
• Passing backup_gateway_code in an API request routes the transaction to the associated gateway if the gateway specified in gateway_code is in failover. If the code is absent or doesn't match a configured gateway, the transaction will fail.
• Applying backup gateway codes to subscription(s) renewals via API request is not supported.
• The backup_gateway_code does not persist for recurring transactions, routing all subsequent subscription renewals to the default gateway unless updated using the gateway_code parameter in a separate call (see "Update the gateway_code via a PUT request" for details.)
• Backup gateway code usage is not supported in the V2 api.

Standard gateway routing

If no gateway_code is passed, Recurly routes the transaction to the Default Gateway if it supports the combination of payment method, card type, and currency. If the Default Gateway doesn't support the transaction, Recurly looks for another configured gateway that matches.

You may specify a backup_gateway_code to target failover, even if you don't specify a targeted gateway_code in your request. You will want to ensure the backup gateway can handle the payment method in use to avoid failures if the primary gateway, or gateway selected, is not available due to a downstream outage or technical issue.

Setup for custom gateway routing