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    

Additional Gateways

Gateway Support

Recurly gateway support is dependent on your business location. Please see http://recurly.com/gateways for gateways supported in your country.

Accepted Payment Types

Recurly supports credit/debit payments from most card type approved by your merchant bank account and payment gateway. However, both Maestro and Laser cards cannot be used for recurring transactions, so Recurly does not support these card types.

Recurly also supports PayPal payments on Hosted Payment Pages for approved merchants.

Supported Gateways

Authorize.net
Bambora
Braintree
Chase Paymentech Orbital
CyberSource
First Data GGe4
Vantiv and Litle
Merchant eSolutions
Payeezy
PayPal Payflow Pro
PayPal Payments Pro
SagePay
Stripe
TSYS
Wirecard
Worldpay

Authorize.net

For pricing and signup information for a new production Authorize.net account, please visit Authorize.net.

Address Verification Service (AVS)

If your company accepts payments from international customers, you need to be aware of some the AVS shortcomings. Currently, AVS fails to match zip codes if the zip code contains letters. US Zip Codes are numeric but many international postal codes will contain letters and will fail to match on the zip code. In order to use AVS with international credit cards, we recommend allowing the transaction to proceed if the street address OR zip code matches.

Card Code Verification (CCV)

When a subscription is first created or a credit card number is updated, Recurly will submit the card number and CCV to your payment gateway. PCI regulations do not allow anyone to store CCV values (regardless of encryption), so it can only be used for the first request. Submitting the CCV with the first request increases the likelihood that the transaction will be approved and will reduce fraud. Banks typically allow subsequent transactions to process if previous transactions have been processed by the same merchant without problem.

API Login ID and Transaction Key

Recurly needs your API Login ID and Transaction Key in order to communicate with your Authorize.net account. Within your Authorize.net account, navigate to Account → Settings → API Login ID and Transaction Key.

Once you have obtained your credentials, please enter them into Recurly's Payment Gateway configuration.

Bambora

To configure Recurly with a Bambora account, you will need:

  • API username, also known as a Merchant ID
  • username
  • API password

The API username and password are configured under Administration → Account Settings → Order Settings → Use username/password validation against transaction. You'll need to check that checkbox and then create a username and password.

Note: The API user for Recurly is different than the normal user accounts configured in the Bambora User Manager. This is an important distinction as the API user credentials are required for proper authentication. While regular login details may work for certain transactions, you may have issues in the future unless the appropriate API credentials are used. We recommend taking one of the following steps to appropriately configure these credentials:

  1. Read through Bambora's documentation on setting up the appropriate API authentication values, then update your Bambora configuration in Recurly with these values.
  2. Contact Bambora's Customer Experience team for assistance in setting up those API values, then update your Bambora configuration in Recurly appropriately.

American Express

Please note: American Express prevents Canadian merchants from accepting USD American Express unless you have an entity located within the United States.

Braintree

Recurly supports Braintree gateway. Recurly does not support 3D Secure with Braintree. Merchants requiring 3D Secure can use Recurly's Hosted Payment Pages with Wirecard or Sage Pay.

Braintree & Multi-currency

Merchants wishing to use Braintree and multi-currency must configure multiple Braintree gateways - one for each currency. Please use your Merchant ID, Merchant Account ID, public key and private key. The Merchant Account ID identifies the currency that is available.

Merchants can find their merchant account IDs by logging into the control panel, clicking "Account > Processing" (in the upper right-hand corner of the page), then scrolling to the bottom of the page. The merchant account IDs available will be found in the 'Merchant Account ID' column in that table.

Processing Paypal transactions through Braintree

Recurly now supports PayPal transactions to be processed through Braintree. Please make sure that your Braintree merchant account is configured correctly to accept PayPal transactions.

We recommend that you use Recurly.js v4 to launch the PayPal one-touch checkout flow. See the Recurly.js PayPal section for more details.

Please note that you will notice subtle differences in how the payment method information for the transaction details displayed in Recurly Admin -- primarily because Recurly receives and stores Braintree’s vault token (and not the actual PayPal Billing Agreement). Recurly will use Braintree’s vault token for all subsequent payment transactions.

Chase Paymentech Orbital

Recurly supports the Chase Paymentech Orbital, Salem Platform. In order for Recurly to connect to your Orbital account, you must ask Chase to configure your Orbital gateway to allow connections from Recurly. At the moment, we only support the Salem Platform. Recurly is a certified Orbital Submitter; not just a certified integrator of the gateway.

Currencies

The Tampa platform only supports US Dollars and Canadian Dollars. Due to this limited currency support, Recurly does not support this platform.

The Salem platform supports many more currencies. Please contact Chase for more information.

CyberSource

To configure the CyberSource gateway you'll need your account username and a Transaction Security Key for the SOAP Toolkit API.

To get a Transaction Security Key, do the following:

  1. Log into your CyberSource business gateway

  2. Navigate to Account Management → Transaction Security Keys → Security Keys for the SOAP Toolkit API.

  3. Click on Generate Key.

  4. Copy the new key into the password field of your [Payment Gateway configuration][1] in Recurly.

Address Verification System (AVS) Settings

Merchants using CyberSource have the option to enable AVS checks for all transactions, only US/Canada transactions, or to disable AVS checks altogether. Recurly recommends enabling AVS for US and Canada only (this setting can be found when configuring/editing a CyberSource gateway).

AVS checks typically work best for the US and Canada, and are sometimes inconsistent or not supported in other countries. CyberSource has the ability to decline transactions based on the AVS result, and the above options allow you to choose whether or not to bypass AVS checks for certain countries.

First Data Global Gateway e4 (GGe4)

Recurly supports First Data’s GGe4 gateway for US merchants. In order to connect to your First Data account, you will need the following:

  • Gateway ID
  • Password
  • HMAC Key ID
  • HMAC

User for Transaction Search API

We strongly recommend that you create a separate account for Recurly to automatically query the transaction status. This is useful when 1) the GGe4 gateway is unresponsive or 2) there is a network issue after a transaction is submitted. Enter the credentials for the read-only user in the gateway configuration page.

In order to create a read-only user:

1) Log into the First Data GGe4 Gateway portal at https://globalgatewaye4.firstdata.com/?lang=en.

2) Click on the "Administration" tab on the far right

3) Click "Create New User" link

4) Create a user named something like "recurly_query"

5) Under the "Login" tab, give the user the "read only" role

After the user is created, please click the user and then visit the "Merchant / Terminal Restrictions" tab to verify the user has access to the terminals that Recurly uses to create transactions on your behalf.

AVS Settings

When adding a new credit card in Recurly, a transaction is created and the provided billing address is submitted to the payment gateway alongside other transaction information. An AVS (Address Validation System) response is then returned to Recurly. AVS checks generally work for US and Canada addresses, but can be inconsistent or unsupported for other countries. This can lead to transactions from customers outside the US/Canada being rejected due to their billing address.

The First Data GGe4 gateway gives you the option to require a partial match on AVS responses for transactions (recommended), or to ignore the AVS response altogether (in which case transactions will not be rejected due to any AVS issues). If the partial match option is enabled, transactions with an AVS response of "N" (No Match) will be rejected. All other AVS responses will be allowed.

Please note: AVS responses are only validated on initial transactions (ie; when a credit card is first added in Recurly). AVS responses for recurring transactions will be ignored.

WorldPay US eCommerce (formerly Vantiv)

Recurly supports WorldPay US eCommerce (Litle platform) for US merchants. Before Recurly can connect to your WorldPay US eCommerce account, you must first ask WorldPay to allow Recurly to connect.

WorldPay Automatic Account Updater

Recurly supports Account Updater regardless of your gateway. If you additionally choose to enable WorldPay's (formerly Vantiv) Automatic Account Updater, please indicate it in your gateway settings. This enables Recurly to submit one additional attempt after a hard decline in order to pick up any potential updates from WorldPay.

Fraud Filtering

WorldPay (formerly Vantiv) provides a suite of products that assist in the discovery of fraud. Recurly highly recommends that merchants using WorldPay enable this feature. Please contact your WorldPay account manager for more information.

Merchant eSolutions

Recurly supports Merchant eSolutions (MeS) for US merchants. In order to connect to your Merchant eSolutions account, you will need to know your Profile and Profile Key from MeS.

Address Verification Service (AVS)

Merchant eSolutions runs AVS on recurring transactions. This allows their merchants to get the lowest interchange rate on card-not-present transactions.

Payeezy

Recurly supports First Data’s Payeezy gateway. In order to connect to your Payeezy account, you will need the following:

  • API Key
  • API Secret
  • Merchant Token

After you setup your Payeezy credentials, Recurly will verify your credentials.

CVV Settings

CVV is a basic yet effective way to block fraudulent transactions. Recurly can easily distinguish between a subscription signup and a renewal transaction. Please disable CVV checks in Payeezy and enable them in Recurly.

PayPal Payflow Pro

PayPal Payflow Pro is a payment gateway only product. Recurly supports Payflow Pro in the US, UK, Canada, and Australia for credit card payments.

Enter the details that you use to access https://manager.paypal.com/ as follows:

Please note, these are not the details from your standard PayPal account (your email) or your API credentials.

PayPal Payments Pro

Recurly can use PayPal's Payments Pro to process credit cards. WebSite Payments Pro acts as a payment gateway for credit card processing and merchant account in one.

To get started with PayPal's Payments Pro, you only need to sign up for their base account. You do not need their Recurring Payments feature---that's completely handled by Recurly.

Payments Pro only works for merchants located in the US, Canada, and UK. Due to PayPal restrictions, we cannot integrate with PayPal Website Payments Pro in any other country.

Card Security Code (CSC)

Some PayPal accounts are required to present the Card Security Code (CSC) for every transaction. After you setup your PayPal credentials, Recurly will verify your credentials. If Recurly determines your account requires CSC for every transaction, you will need to contact PayPal to disable this requirement before your account can be used with Recurly.

Important Note: By default, Recurly requires the CSC (also known as CVV) to start a new subscription or transaction. Due to PCI requirements, Recurly cannot store the CSC. Therefore, Recurly submits recurring transactions without the CSC, and your PayPal account must be configured to not require this value.

Configuring Recurly to use PayPal

Recurly requires the PayPal API Username, API Password, and Signature (preferred) or PEM Certificate to connect to your PayPal Payments Pro account. To retrieve your Signature from PayPal, follow these steps:

  1. Log in to your PayPal account at paypal.com

  2. On the My Account tab, click on the Profile sub-tab.

  3. Click on API access or Request API credentials, depending on your PayPal account type.

  4. PayPal will present two options: granting API permissions (Option 1) and requesting API credentials (Option 2). Select option 2. It may say View API Signature or View API Credentials.

  5. If you have already requested an API Signature, you will now see your API credentials. Otherwise,

  6. The final page will display your API username, password and signature. All three pieces are required to connect Recurly to your PayPal Website Payments Pro account.

PEM versus Signature

Recurly supports connecting to your PayPal account using the PEM or signature for credit card transactions. If in the future you wish to support payments via PayPal (in addition to credit cards), you must use the signature API credentials. If you have created a PEM certificate, you will need to delete the PEM certificate and walk through the process of choosing the signature credentials.

Canada and American Express

Please note, PayPal Website Payments Pro in Canada does not support American Express.

Address Requirements

PayPal Payments Pro requires full address information to be submitted for every transaction. If you are using PayPal WPP, please set Recurly to require the full billing address (name, phone, street address, city, state/province, postal/zip, and country).

SagePay

Recurly supports the Sage Pay gateway in the UK. A continuous authority merchant account number is required to work with Recurly and Sage Pay.

Sage Pay Setup

When configuring your Sage Pay setup, choose I want to use my own payment pages and leave the Form and Server product checkboxes unchecked.

Sage Pay requires a test transaction and refund against their test server to finalize your setup. Please contact Recurly support for assistance connecting to SagePay's test server. SagePay's instructions for processing these test transactions can be found at http://www.sagepay.co.uk/support/12/36/test-card-details-for-your-test-transactions.

IP Addresses

Sage Pay requires a list of padded IP addresses and their corresponding subnet masks that will issue transactions on your behalf. You can read the details on how to whitelist IP address on your merchant account. Please contact support to get a list of Recurly IP addresses to whitelist on your merchant account.

Note: Merchants requiring 3D Secure with their Sage Pay account must use Recurly's Hosted Payment Pages for customer checkout. Please contact support if you'd like notification when 3D Secure support is added to other integration methods.

Velocity

Sage Pay supports limited requests per second. Merchants may contact Sage Pay support to add addition TIDs, which will allow for additional high velocity processing.

Stripe

To integrate with Stripe, please access the Recurly Payment Gateway Configuration page. You may either log in with your existing Stripe account, or apply for a new Stripe account.

Recurly's Stripe integration will not update Stripe customers as accounts update their billing information. Should you choose to process any payments directly inside of Stripe, please search for the most recently created Stripe customer.

In the future, the Stripe integration will automatically update existing Stripe customers with updated billing information. Please contact Support if you'd like updates on Recurly's Stripe integration.

TSYS

The TSYS Gateway can connect to over 400 merchant account banks in the United States

Please ask your merchant bank to create a TSYS Merchant Profile using Host Capture (Summit platform) for Recurly, version 1.0. Once the profile is created, please send the merchant profile along with your POS ID, Authentication Code, and zip code to support@recurly.com.

Getting started
To get started, Recurly needs to know how to connect to your merchant account. If you have a merchant account, see the instructions for connecting to an existing merchant account. Otherwise, start with creating a new merchant account.

New Merchant Accounts
If you need a merchant account, we can help you get started. Create a Recurly account, or log into your existing account, and the payment gateway setup process will walk you through the application for a new merchant account.

Existing Merchant Accounts
If you have an existing merchant account, please ask your merchant bank to create a TSYS Merchant Profile using Host Capture (Summit platform).

Your merchant bank account provider will need to contact Recurly with your Authentication code, POS ID, merchant zip code, and approved payment methods. POS ID should be 15 numbers and Authentication code is 6-10 letters/numbers. Once this data is received, you can expect to have the Recurly gateway configured on your site in one business day.

Important Note: If you ever change address or phone number, make sure to contact your merchant account provider ahead of time to check if you need an updated merchant profile. Changing your address sometimes requires updated merchant account credentials, and if you don't update your TSYS gateway configuration with those credentials you may experience downtime until a new VAR sheet is generated.

Advanced

Multi Currency
Today, the TSYS integration is only available for US merchants and for US Dollars. You may combine with other gateways to accept additional currencies.
Merchant Geography
TSYS can process credit cards from customers around the world. However, it is only available today for merchants with a US based presence.
Address Requirements
TSYS has no minimum address requirements.
CVV Requirements
Because TSYS is designed to handle recurring billing, there is no Card Security Code configuration needed.

Wirecard

Recurly supports Wirecard Credit Card Processing as a payment gateway.

Note: Merchants requiring 3D Secure with their Wirecard account must use Recurly's Hosted Payment Pages for customer checkout. Please contact support if you'd like notification when 3D Secure support is added to other integration methods.

WorldPay

Configuring WorldPay WPG for international processing

  1. Contact WorldPay to configure your merchant account.
  2. Login to the WorldPay portal and whitelist Recurly's IP addresses (please contact support for the appropriate IPs).
  3. While logged into WorldPay, set the Capture delay to 1-Day.
    a. Configure callbacks with the urls https://callbacks.recurly.com/worldpay, and select which notifications you'd like to receive.
  4. We also recommend that you configure WorldPay notifications to be sent to Recurly. This will help keep Recurly's transaction status in sync with WorldPay's status.

Configuration in Recurly

  1. Go to the “Payment Gateways” page in your Recurly app. Click on “Add Payment Gateway” and then choose the WorldPay gateway.
  2. Enter your WorldPay MerchantCode, UserName and Password credentials.
  3. Choose the currencies and card types you want to support.
  4. If necessary, select the card types you'd like to apply Zero Dollar Authorizations to.
  5. Click "Save".
  6. Once the gateway configuration is saved, you can verify the settings by clicking the “Test Configuration” option associated with the gateway.

Voids and Refunds
Void (also known as 'cancel') and Refund order modifications are processed asynchronously by WorldPay. There is a remote chance that WorldPay may reject a Void or Refund request 5 to 45 minutes after receiving receiving it.

Billing Address
At Recurly, we want to submit as much information (including the billing address) to WorldPay as possible. WorldPay, however, requires four mandatory fields - Address line1, City, Postal code and Country. If not provided, Recurly may use default values for these fields.

For example: If a customer has only provided a postal code we will submit the provided Postal code, use the country from their IP address, and default the City to “city” and Address line1 to “address”. If we don't have the Country (or can’t derive the country from the IP address) a billing address will not be submitted for the transaction.