New Card Type Support - China UnionPay
Recurly is pleased to announce that we now support the China UnionPay card type through our Chase Orbital gateway integration. Learn more.
Gateway Specific Updates for PSD2
The gateways supported by your Recurly site is dependent on your business location. Please see our gateway page for the specific gateways supported in your country.
Recurly supports credit / debit payments from most card types approved by your merchant bank account and payment gateway. However, Maestro cards cannot be used for recurring transactions, so Recurly does not support this card type.
By default, all transactions are processed at level I rates. For certain gateways, Recurly also supports level II card data, which will allow you to qualify for lower interchange rates when processing qualified transactions as a US merchant. This involves the inclusion of the following data fields:
- Sales tax amount
- Customer code / PO number
- Merchant zip code
The following gateway integrations currently support level II card data via Recurly:
What you need to do to benefit from level II card data support: Recurly will include necessary data fields automatically when formatting your transaction requests to the gateways called out above. Given this, you'll simply need to ensure that sales tax is being collected / calculated through Recurly to ensure that your gateway can submit transactions to your processor with the appropriate level 2 data fields. If the transaction qualifies for level 2 rates, this would be addressed while the transaction is processed by the card network.
Chase Paymentech Orbital
First Data GGe4
PayPal Payflow Pro
PayPal Payments Pro
Opayo (previously SagePay)
For pricing and signup information for a new production Authorize.net account, please visit Authorize.net.
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.
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.
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.
To configure Recurly with a Bambora account, you will need:
- API username, also known as a Merchant ID
- 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:
- Read through Bambora's documentation on setting up the appropriate API authentication values, then update your Bambora configuration in Recurly with these values.
- Contact Bambora's Customer Experience team for assistance in setting up those API values, then update your Bambora configuration in Recurly appropriately.
Please note: American Express prevents Canadian merchants from accepting USD American Express unless you have an entity located within the United States.
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.
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.
Recurly supports the Chase Paymentech Orbital, Salem Platform. In order for Recurly to connect to your Orbital account, you must configure a few steps on both Chase and Recurly to get the integration working correctly.
1) To start you must be on the Chase Paymentech Orbital, Salem Platform for the integration to work correctly. Chase offers a few different processing platforms, at this time we only support the Salem Platform.
2) Configuring Chase: Recurly is a certified Orbital Submitter; not just a certified integrator of the gateway. To set up your chase account you would want to reach out to Chase directly and ask them to setup your Chase account to allow connections from Recurly, a Certified Orbital Submitter on the Salem Platform. If Chase asks for our submitter ID that can be found here https://docs.recurly.com/docs/chase-orbital-gateway-setup. Generally that is sufficient information for chase to allow connections, in some cases they might ask for specific IP addresses that are used to sent transactions from Recurly to chase, if they require the IP addresses those can be found here https://docs.recurly.com/docs/ip-allowlist
3) You would want to obtain your Merchant Account ID, Username, and Password from Chase so that when you go to add the Chase gateway in your Recurly site you can fill out those fields to correctly connect your Recurly site to your Chase Paymentech gateway.
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.
Recurly supports China UnionPay via Chase Orbital. Please contact Chase Support to have this card brand enabled before enabling China UnionPay as an accepted card type within your Chase Orbital gateway configuration in Recurly.
To configure the CyberSource gateway you'll need your MerchantID for the Login, and a Transaction Security Key for the SOAP Toolkit API.
To get a Transaction Security Key, do the following:
Navigate to Account Management → Transaction Security Keys → Security Keys for the SOAP Toolkit API.
Click on Generate Key.
Copy the new key into the password field of your [Payment Gateway configuration] in Recurly.
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.
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
- HMAC Key ID
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. First Data docs on Results API.
- 'Results API' credentials expire every 60 days. Be sure to update your credentials prior to the deadline.
- Failure to update the 'Results API' credentials will result in requests with an invalid_credentials error. If there are 12 of these bad requests made in 15 minutes, the entire integration may be shut down due to an "IP-Lockout" scenario.
In order to create a read-only user:
1) Log into the First Data GGe4 Gateway portal at
2) Click on the "Administration" tab on the far right
3) Click "Create New User" link
4) Create a user name
5) Under the "Login" tab, give the user the "read only" role
First Data's documentation on how to create an account here.
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.
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.
To enable your Vantiv gateway, you will need to enter the MID for your Vantiv gateway on the credentials page within Recurly.
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.
Recurly supports WorldPay US eCommerce (Vantiv - 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.
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.
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.
Recurly supports Merchant eSolutions (MeS) for US merchants. In order to connect to your Merchant eSolutions account, you will need to know your
Profile Key from MeS.
Merchant eSolutions runs AVS on recurring transactions. This allows their merchants to get the lowest interchange rate on card-not-present transactions.
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 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 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:
- Vendor: The MERCHANT LOGIN you use to access https://manager.paypal.com/
- Password: The PASSWORD you use to access https://manager.paypal.com/
- User: The MERCHANT LOGIN you use to access https://manager.paypal.com/
- Partner: Optional (PayPal may supply you with this)
Please note, these are not the details from your standard PayPal account (your email) or your API credentials.
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.
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.
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:
Log in to your PayPal account at paypal.com
On the My Account tab, click on the Profile sub-tab.
Click on API access or Request API credentials, depending on your PayPal account type.
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.
If you have already requested an API Signature, you will now see your API credentials. Otherwise,
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.
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.
Please note, PayPal Website Payments Pro in Canada does not support American Express.
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).
Recurly supports the Opayo gateway in the UK. A continuous authority merchant account number is required to work with Recurly and Opayo.
When configuring your Opayo setup, choose I want to use my own payment pages and leave the Form and Server product checkboxes unchecked.
Opayo requires a test transaction and refund against their test server to finalize your setup. Please contact Recurly support for assistance connecting to Opayo's test server. Opayo'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.
Opayo 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 allow IP address on your merchant account. See our IP Allowlist documentation for the full list of IPs to supply.
Note: Merchants requiring 3D Secure with their Opayo 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.
Opayo supports limited requests per second. Merchants may contact Opayo support to add addition TIDs, which will allow for additional high velocity processing.
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.
If you use Stripe and Gateway Failover, you must make sure the two gateways match the same currency and card type support.
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 suppor[email protected]
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.
Today, the TSYS integration is only available for US merchants and for US Dollars. You may combine with other gateways to accept additional currencies.
TSYS can process credit cards from customers around the world. However, it is only available today for merchants with a US based presence.
TSYS has no minimum address requirements.
Because TSYS is designed to handle recurring billing, there is no Card Security Code configuration needed.
- Contact WorldPay to configure your merchant account.
- Login to the WorldPay portal and allow Recurly's IP addresses. See our IP Allowlist documentation for the full list of IPs to supply.
- 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.
- 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.
- Go to the “Payment Gateways” page in your Recurly app. Click on “Add Payment Gateway” and then choose the WorldPay gateway.
- Enter your WorldPay MerchantCode, XML UserName and XML Password credentials. Please keep in mind that the UserName and Password details will not be the ones you use to log into your WorldPay merchant account.
- Choose the currencies and card types you want to support.
- If necessary, select the card types you'd like to apply Zero Dollar Authorizations to.
- Click "Save".
- Once the gateway configuration is saved, you can verify the settings by clicking the “Test Configuration” option associated with the gateway.
Worldpay Payment Gateway (WPG) requires you to enter XML credentials obtained from Worldpay.
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.
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.
Updated 2 months ago