Gateways & payment methods configuration

Configure payment gateways in Recurly — add credentials, set card types, enable Zero Dollar Authorizations, manage failover, and switch gateways without losing customer payment data.

This page covers how to add and configure payment gateways in Recurly — including credential setup, card type selection, Zero Dollar Authorizations, payment routing, gateway failover, and switching gateways.

1Gateway configuration 2Test configuration 3Enabling/disabling a gateway 4Payment routing 5Switching gateways 6Gateway downtime 7Zero Dollar Authorizations 8Validations 9Fraud velocity checks

Gateway configuration

If you don't yet have a gateway, visit recurly.com/gateways to explore supported options. When choosing a gateway, consider: the region your company is based in, the regions where your customers are, and your customers' payment preferences.

Once you have a gateway, follow these steps to add it to Recurly:

Open Payment Gateways

From your gateway configuration page, click Add Gateway.

Select your gateway

Choose your payment gateway from the list. If you don't see the right gateways for your location, check your company country settings in your Business Entity.

Enter your credentials

Input your gateway credentials. These are typically API credentials, not your virtual terminal login. See the gateway-specific documentation for details.

Set accepted card types

Select the card types you want to accept. Confirm the same card types are also supported and enabled on your gateway account.

Configure Zero Dollar Authorization (ZDA) settings

If your gateway supports ZDA, configure which card types use it. Test billing info updates for every accepted card type after enabling ZDA. Not all gateways require this setting — ZDA support is implied on some gateways and doesn't require configuration.

Add Recurly IPs to your gateway allowlist (if required)

If your gateway requires IP allowlisting, see the IP Allowlist documentation for the full list of IPs to supply.

Set up webhooks (if required)

If your gateway requires webhooks, follow your gateway's individual configuration instructions to ensure transactions are updated correctly.

Test configuration

Once a gateway is configured, use the Test Configuration option for a basic verification check. When your site is in production mode, Recurly recommends running a test transaction (and then voiding it) to fully validate the gateway setup before going live.

Enabling/disabling a gateway

A gateway can be enabled or disabled at any time to control which gateway receives transactions. In the gateway edit page, toggle Gateway Status between Enabled and Disabled. Gateways are set to Enabled by default when first added.

Payment routing

For accounts with multiple gateways, Recurly routes transactions based on accepted card type and currency. Beyond that, Recurly sends transactions to the gateway added first. To specify a gateway per transaction, use Recurly's Custom Gateway Routing.

Switching gateways

Because Recurly stores customer credit card data, you can switch payment gateways at any time. Disable or delete the old gateway, enable the new one, and Recurly will automatically route transactions to the new gateway — as long as it supports the same card types and currencies as the previous one.

Note that not all payment data migrates easily, especially tokenized payment instruments. Contact Recurly Support before switching if you have a specific migration use case.

Refunds process through the original gateway Refunds always process through the gateway that handled the original charge. Keep your old gateway account active in Recurly — but disabled for new transactions — until you no longer need to issue refunds for transactions it processed, or until the maximum refund window has elapsed.

Gateway downtime

If a payment gateway is unreachable, Recurly automatically retries recurring transactions every 2–4 hours until the gateway responds or a maximum of 20 payment failures is reached.

Zero Dollar Authorizations (ZDA)

Zero Dollar Authorizations let you verify a customer's payment method without placing a temporary hold on their card. This reduces customer support inquiries around unexplained card charges.

Prerequisite: ZDA must be enabled on your payment gateway account. Contact your gateway provider to confirm support and activate the feature before enabling it in Recurly.

Open Payment Gateways

In Recurly, navigate to Configuration → Payment Gateways.

Open the gateway edit page

Locate the gateway you want to configure and select Options → Edit Gateway.

Enable ZDA per card brand

Find the Zero Dollar Authorizations (Advanced) section and check the box for each card brand you want to enable ZDA for.

Save your changes

Click Save Changes.

How ZDA works To verify a card, gateways like Stripe send an authorization request to the issuing bank. Enabling ZDA instructs the gateway to send this request for $0 instead of a higher amount.

Validations

Recurly runs the following validations before passing a transaction to your gateway:

Credit card number passes the Luhn check
CVV format matches the selected card type
Expiration date is in the future and in the correct format
Zip code format is valid (when a country code is supplied, for supported countries)
Address information is present based on your site-level address requirements

Fraud velocity checks

All transactions pass through a fraud velocity filter before reaching your payment gateway. See the transactions documentation for details on the fraud check system and how to configure it.

Updated 6 days ago

Did this page help you?