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    

Payment Gateways

Payment gateways are responsible for processing transactions and distributing funds into your merchant bank account.

Gateway Configuration

If you don't have a gateway yet, please see our Getting Started documentation for instructions. If you already have a gateway, follow these steps:

  1. From your gateway configuration page, click Add Gateway

  2. Select your payment gateway (not seeing the right gateways for your location? Check your company country settings in your Site Settings).

  3. Enter your gateway credentials. These are typically not the credentials you use to access your virtual terminal but a set of API credentials. Please see our gateway-specific documentation for instructions on obtaining gateway API credentials.

  4. Set your accepted card types. Recurly will be able to collect payments from any card type supported by your payment gateway---the one exception are Maestro cards, which cannot be used for recurring transactions.

  5. Configure your Zero Dollar Authorization (ZDA) settings. Please test updating billing information with every card type you accept after enabling Zero Dollar Authorizations.

Test Configuration

Once a gateway is configured on your Recurly site, the test configuration option can be used for a basic verification check. When your site is in production mode, Recurly recommends running a test transaction (and then voiding the charge) to fully validate your gateway setup before you go live.

Payment Routing

For accounts with multiple gateways configured, Recurly will route transactions based on accepted card type and currency. Beyond those settings, Recurly will send the transaction to the gateway first added to the account. Merchants are able to specify which gateway will be used per transaction by utilizing Recurly's Custom Gateway Routing functionality.

Enabling/Disabling Gateway

A payment gateway can be enabled or disabled at any time to allow transactions to flow to another gateway. Simply enter the gateway edit page and check or uncheck Enabled for New Transactions.

Switching Gateways

Because Recurly stores your customer credit card data, you can easily switch payment gateways at any time. Simply disable/delete the old payment gateway and enable the new---Recurly will automatically funnel transactions to the new payment gateway.

Gateway Downtime

If for any reason your payment gateway is not reachable, Recurly will automatically retry your recurring transactions every 2--4 hours until either the gateway is reached or a maximum of 20 payment failures occurs.

Zero Dollar Authorizations (ZDA)

Your payment gateway settings can be configured for Zero Dollar Authorizations (ZDA), bypassing the default $1.00 authorization for billing information updates. ZDA transactions can only be processed when billing address information is present and your payment gateway supports this authorization type.


Recurly works to save you money by passing some basic validations before passing the transaction to your payment gateway. This includes:

  1. Validating that the credit card number is a valid number (ie; passes Luhn check)
  2. Validating that the CVV format matches the card type selected
  3. Validating a future expiration date format
  4. Validating the zip code format (when country code is supplied, for limited countries)
  5. Validate the entry of address information based on site-level address requirements.

Fraud Velocity Checks

All transactions are passed through a simple fraud velocity filter before being passed on to your payment gateway. Please see the transactions documentation for details on our fraud check system and how you can take full advantage of it.

Payment Gateways

Payment gateways are responsible for processing transactions and distributing funds into your merchant bank account.

Suggested Edits are limited on API Reference Pages

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