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

Custom gateway routing (merchant-initiated)

Use Recurly's Custom Gateway Routing to direct transactions to a specific payment gateway by passing a gateway_code — for fund segregation, acceptance rate optimization, and subscription routing control.

Custom Gateway Routing lets you direct transactions to a specific payment gateway by passing a gateway_code in your API requests. Use it to segregate funds, optimize acceptance rates through local processors, and control exactly which gateway handles each transaction or subscription renewal.
Not included in Starter or Pro — contact Recurly Sales to upgrade
1Definition 2Key benefits 3Key details 4Setup

Prerequisites

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

Limitations

  • Card on File Mandates — Depending on the gateway, Card on File mandate data is packaged in different formats. In most cases the raw network transaction ID is accepted and recurring transactions process normally. In rare cases, the data is incompatible and failover will not occur.
  • 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.
  • 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

Custom Gateway Routing is a Recurly feature that lets merchants direct transactions to a specific payment gateway by passing a gateway_code parameter in API requests. It supports fund segregation, acceptance rate optimization, and granular routing control across subscriptions and one-time transactions.

Key benefits

Financial reporting efficiency Separate funds across specific gateway accounts to simplify financial reporting.
Business-centric routing Direct transactions based on your specific business logic, giving you control over which gateway handles each payment.
Enhanced acceptance rates Route transactions through local processors to reduce cross-border failures and improve approval rates.
Recurring transaction management Update gateway routes for recurring subscriptions at any time to align with renewals and changing business needs.

Key details

Supported transactions and payment methods

Supported transaction types:

  • One-time transactions
  • Initial subscription transactions (and subsequent recurring transactions)
  • Recurring subscription renewals

Supported payment methods:

gateway_code behaviour

  • 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 persists for recurring transactions, routing all subsequent subscription renewals to the specified gateway unless updated.
  • 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.

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.

Setup for custom gateway routing

1

Obtain the gateway code

In your Recurly account, go to the gateway configuration page. Each configured gateway has a unique gateway_code generated by Recurly. Note the code for the gateway you want to route transactions to.

2

Identify your API endpoint

Custom Gateway Routing is available via the v2/purchases and v3/purchases endpoints. Use the appropriate version for your integration.

3

Pass the gateway_code in your API request

Include the gateway_code parameter at the root level of your request to the purchases endpoint. This directs the transaction to the specified gateway.

4

Use a supported client library

Custom Gateway Routing is supported across all Recurly-provided client libraries. Confirm you're using a current supported library.

5

Review your configuration

Visit the gateway configuration page in Recurly to confirm your gateways and their associated gateway_code values.

6

Test the setup

Run a few test transactions and monitor their routing to confirm they're directed to the specified gateway per the gateway_code in your requests.