Gateways & payment methods configuration

Gateway Configuration

If you don't yet have a gateway, please start here to explore gateway options that Recurly supports. When choosing a gateway, some factors to consider include: region your company is based, region(s) where your customers are based, your customers' payment preferences. 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 Business Entity).

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 on an allowlist, see our IP Allowlist 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 your payment gateway supports this authorization type. Zero dollar authorizations can be configured by doing the following:

1. Contact your gateway to confirm that zero dollar authorizations are supported for your account. If needed, have them enable support for this functionality.
2. Within Recurly, visit Configuration > Payment Gateways.
3. Locate the gateway(s) supporting non-USD currencies.
4. For each gateway identified, select Options > Edit Gateway.
5. On the edit gateway page, locate the section labeled “Zero Dollar Authorizations (Advanced)” and enable ZDAs for each card brand you want to support zero dollar authorizations on.
6. Save changes.

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.