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    

Gateways & Payment Methods

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

Gateway Configuration

If you don't yet have a gateway, please start here to explore gateway options that Recurly supports in your country. 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 more information.

  4. Set your accepted card types. Note, you'll also need to ensure that the card types are supported and enabled on your gateway account.

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

  6. If your payment gateway requires Recurly's IPs to be whitelisted, see our IP Whitelisting documentation for the full list of IPs to supply to your gateway.

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.

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 toggle the Gateway Status between Enabled or Disabled. By default, a gateway will be set as Enabled when first added to Recurly.

Payment Routing

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

Switching Gateways

Because Recurly stores your customers' credit card data, you can easily switch payment gateways at any time. Simply disable/delete the old payment gateway and enable the new one---Recurly will automatically funnel transactions to the new payment gateway as long as it supports the same card types and currencies as your previous gateway account.

Note: Refunds will always process through the gateway account that processed the original charge. Because of this, we recommend keeping your old gateway account active and added to Recurly, but disabled for new transactions, until you no longer need to process refunds for transactions processed through your old gateway or the maximum refund window for your transactions has elapsed.

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.

Validations

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. Validating 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.

Gateways & Payment Methods


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.