Developer HubSupportContactRecurly.comRequest a Demo

Custom Gateway Routing

Recurly’s Custom Gateway Routing functionality will allow merchants to route transactions to a specific payment gateway.

Suggest Edits

Merchant Benefit

By allowing merchants to specify which gateway a transaction(s) should be routed, merchants can:

  • Take advantage of specific gateway accounts to keep funds separate for financial reporting efficiencies.
  • Have direct control over where transactions are routed, enabling routing based on any business use case.
  • Improve acceptance rates, for example by taking advantage of local processors, versus submitting cross-border transactions.

Initial Setup

To use this feature, you must obtain the required gateway code which is available on the gateway configuration page. Custom Gateway Routing using gateway_code is available via the v2/purchases and the v3/purchases API endpoints. If using v3, substitute the appropriate v3 endpoint based on the v2 setup instructions below.

  • Recurly automatically generates a unique gateway_code for each gateway. These are displayed on the gateway configuration page in Recurly. See screenshot below.
    ** Note: custom gateway routing is not limited to the gateways shown in the screenshot below and should work across any gateway using a supported payment method.
  • The gateway_code is a new, optional parameter on the v2/purchases API endpoint. Merchants pass the gateway_code parameter in API requests.
  • Available using all of the supported Client Libraries.

<purchase>
  <gateway_code>jg7fin35hde6</gateway_code>
  <currency>USD</currency>
  <account>
    <account_code>9b8288fb53bc4e56a365fa</account_code>
    <billing_info>
      <address1>123 Main St.</address1>
      <city>San Francisco</city>
      <state>CA</state>
      <country>US</country>
      <first_name>Verena</first_name>
      <last_name>Example</last_name>
      <number>4111111111111111</number>
      <month>12</month>
      <year>2020</year>
      <zip>94105</zip>
    </billing_info>
  </account>
  <subscriptions>
    <subscription>
      <plan_code>premium</plan_code>
    </subscription>
  </subscriptions>
</purchase>

Additional Details

  • If the gateway_code parameter is passed in a request to the v2/purchases API endpoint, the transaction will route to the gateway associated with that unique gateway_code.
  • If no gateway_code is included in an API request, or if the gateway_code does not match any of the codes for the merchant’s gateways, the transaction will route to the merchant’s default gateway.
    • Exclusion: for one-time transactions or initial subscription signup transactions, if a gateway_code is not recognized, Recurly will return an error response and the transaction will fail.
  • The gateway_code will be saved for recurring transactions. Any subsequent subscription renewal transaction with a gateway_code specified will be routed to the specified gateway.
  • If a merchant would like to update a gateway_code, complete a PUT request using the v2/subscriptions/:uuid/notes endpoint, and including the new gateway_code at the root level.
    • If an empty tag is sent using the same endpoint, this will clear any assigned gateway_code, and standard gateway routing logic will take place.
  • Merchants can utilize GET requests to /subscriptions, that will include the gateway_code associated to an account's subscription.
  • Merchants can use the v2/invoices/ endpoint to update the gateway_code to change the specified gateway on the Invoice level.
  • Routing to different gateways is based on having unique Recurly gateway instances. This can either be: A) unique Recurly gateway instance using a different Merchant Account ID / MID for one gateway; or B) unique gateway instance using a different gateway.
  • Routing is tied to a payment method. If a gateway_code is sent for a payment method that the gateway does not support, the transaction will revert to the default gateway for that payment method.
  • Gateway codes will be applied to all subscriptions included in a single API request.
  • If a merchant has Aggregate Invoices functionality enabled, and if subscriptions on an aggregated invoice all have the same gateway_code the invoice will use that gateway. If subscriptions on an aggregated invoice do not all have the same gateway_code, or include a non-specified gateway_code, the invoice will fallback to the default gateway.
  • The gateway_code is displayed on the transaction detail page for each transaction.
  • The gateway_code is included in the Transaction Export for each transaction.
  • The gateway_code is included in webhooks.
  • Gateway routing will be available for the following Recurly payment methods: Credit Cards, PayPal, Amazon Pay, and ACH payments.
    ** This feature does not support payments made through Apple Pay or Adyen HPP.

Transaction Routing flow diagrams

Plan Availability and Pricing

Utilizing the gateway_code for routing transactions is included on Recurly’s Pro and Enterprise plans at no additional per transaction cost.

  • Routing based only on currency or payment method is available on our Starter plan.
  • If you are on Recurly's Starter plan and pass the gateway_code to Recurly, an error will be returned.

Merchant Prerequisites

  • Merchant has multiple gateways for a given payment type (e.g. credit cards) set up within Recurly.
  • Merchant has integrated with the v2/purchases endpoint, and is passing the gateway_code parameter.

Supported transactions

  • One-time transaction.
  • Initial subscription transaction (of subsequent recurring transactions).
  • Recurring subscription renewal transactions.

Supported Payment Methods

  • Credit Cards.
  • PayPal.
  • Amazon Pay.

Standard Gateway Routing

If no gateway_code is passed, Recurly will route transactions based on whether there is a ‘Default Gateway’ if that gateway supports the combination of payment method, card type, and currency for the transaction. If the ‘Default Gateway’ does not support the transaction, Recurly will look for other gateways that have been set up by the merchant that match the transaction’s payment method, card type, and currency.

Notes & Limitations

  • With regards to card brand mandates for Card on File (Stored Credentials) transactions, Recurly will send a card on file indicator specific to the new gateway, as well as a value to indicate the transaction is the first in a series of transactions. Therefore, there should not be an impact on acceptance rates due to Card on File mandates.
  • Passing gateway_code for multiple subscriptions on the same request will not honor routing to different gateways.
  • The Stripe configuration for card brands is managed within your Stripe dashboard. Therefore, Recurly is not aware of which card brands your Stripe integration supports. If there are card brands that your Stripe integration does not support, yet other gateways do support, be sure to specify a gateway_code to ensure that the specific transaction for that card brand is routed to another gateway. Check your Stripe configuration within the merchant portal.

Updated 7 days ago