GoCardless gateway integration documentation, configuration, implementation.


GoCardless + Recurly: Gateway Integration

Recurly’s integration with GoCardless will allow merchants to utilize the strength of the GoCardless platform for using direct debit payment schemes, and the power of Recurly’s subscription platform. Learn more about GoCardless.

GoCardless supports many different direct debit schemes across the globe, giving you international coverage to charge your customers directly from their bank.

PLEASE NOTE: GoCardless has transaction minimums and maximums, which can vary based on payment method. Please make sure these are inline with your business needs. https://support.gocardless.com/hc/en-us/articles/115002831125-Transactions-and-fees-FAQs#transaction_limits

Supported Payment Methods

  • SEPA
  • ACH
  • BACS
  • BECS

Recurly integration details

SEPA and ACH are currently available via HPP, Recurly.js, client libraries and API V2 and V3
BACS and BECS is currently available on Recurly.js, and API V2 and V3.
Note: For BACS, BECS, and ACH, please reach out to support to get this feature enabled.

Configuration to support GoCardless payments

In order to process transactions via GoCardless + Recurly, merchants will need to complete the following integration steps.

GoCardless configuration

There are steps merchants need to take within GoCardless, including:

  1. Ensure that the payment method is enabled on your GoCardless gateway.
  2. Have a GoCardless merchant account and credentials already provisioned, and enter your credentials via the ‘Add Payment Gateway’ page within Recurly and the GoCardless OAuth flow. This will allow your existing merchant account to be used by Recurly.
  3. Apply for (or create) a merchant account via the ‘Add Payment Gateway’ page within Recurly and the GoCardless OAuth flow.
  4. Once you have signed up for a GoCardless account through Recurly, merchants will need to complete the onboarding flow with GoCardless and have the account approved. NOTE: Ensure that your merchant account and creditor identifier have been approved by GoCardless before transacting.
  5. See screenshots of steps below.

A note on credentials

GoCardless provisions only one access token per organization at a time. A merchant's organization will have only one email address associated with your organization. Merchants use this email address to connect their Recurly account to GoCardless. If you use the same email address to connect to Recurly a second time (including on a different Recurly site like your staging or development site for example), you will invalidate the credentials for any previously configured GoCardless gateway in Recurly. This will create transaction processing issues, please take care not to do this.

It is possible to use the same email address to connect Recurly to a GoCardless Sandbox account and to a GoCardless Production account. Because these are different databases in GoCardless, using the same email address will not invalidate your access tokens.

Merchants should use a set of GoCardless credentials only once across Recurly sites. When you sign up for a GoCardless merchant account, GoCardless gives your account an organization id. GoCardless later uses that organization id to message transaction events to Recurly. In order for Recurly to update transaction events correctly, you need to have only one GoCardless organization ID across your Recurly sites.

Recurly Configuration

  1. Configure your GoCardless payment gateway within Recurly.
  • Ensure the correct currencies are enabled for your site, by completing within Recurly under: Configuration/Currency. SEPA - EUR, ACH - USD, BACS - GBP, BECS - AUD
  • If you do not see GoCardless as a gateway option, please contact [email protected] to enable it for you.
  1. Recurly Plans:
  • Be sure the relevant currencies are enabled for your plan. SEPA - EUR, ACH - USD, BACS - GBP, BECS - AUD
    To do this: Recurly - Configuration - Currencies - enable relevant currencies
  1. Address requirements.
  • Certain payment methods have minimum address requirements to process a payment. For example, ACH will require full address to be included in transaction requests, so please be sure to collect these fields during checkout. Confirm with GoCardless if any other payment methods have specific address requirements.
  1. Hosted Page configuration: (Optional)
  • Enable both Hosted Payment Pages, and Hosted Account Management Pages in your ‘Hosted Pages’ configuration.
  • Be sure to collect first and last name on your hosted pages as these are required for GoCardless transactions.
  1. Emails:
  • There are specific notifications merchants are required to send for to direct debit shoppers, these can vary by payment method but are categorized into: New Subscription, Subscription Change, and Payment Notification.
  • Recurly supports these email templates, please verify the timing of your email communications based on the relevant payment methods by consulting GoCardless documentation, here.
  1. Webhooks:
  • Be sure to utilize Recurly’s webhooks to understand the status of your transactions. This is very important to ensure since Direct Debit transactions are asynchronous in nature. Learn more about setting up webhooks with Recurly.
  1. Dev Mode: When you're ready to test - reach out to [email protected] and ask them to put you site in dev mode. Dev mode will allow you to connect Recurly Sandbox to GoCardless Sandbox and test your transaction flows!

API Documentation


GoCardless Compliance Review Required

Utilizing the API to customize your own checkout pages will require review and approval from GoCardless. Be sure to allow time for review into your development cycle, and reach out to your GoCardless partner manager or the support team for approval.

  1. API V3 supports sending local bank details: IBAN bank details (SEPA), account_number and routing_number (ACH), account_code, sort_code and type (BACS) within the billing_info, account_code, bsb_code (BECS). Learn more.
  2. API V2 supports sending local bank details: IBAN bank details (SEPA), account_number and routing_number (ACH), account_code, sort_code and type (BACS), account_code, bsb_code (BECS) within the billing_info. Learn more.
  3. Recurly.js supports sending tokenized bank account information to Recurly. Note: be sure you are using Recurly.js 4 to have bank account fields available. Learn more about Recurly.js.

Note that first and last name are required by GoCardless.

Adding GoCardless Gateway

  1. Navigate to ‘Add Gateway’ page, and select ‘GoCardless’ gateway. (This selection will need to be enabled by Support).
  1. Apply for a GoCardless merchant account, and complete the necessary onboarding and approval steps. Merchants should not process transactions until your account with GoCardless is fully approved. Merchants can also add credentials for an existing merchant account.
  1. Once added, the GoCardless gateway will appear in your gateway list.

GoCardless Mandates

For each account that is added with GoCardless, a mandate will be created. Learn more from GoCardless about what mandates are, and the importance of mandates. Note: Direct debit schemes will vary in requirements about mandates, make sure you understand the mandate requirements relevant to your site.

Handling Refunds

  1. GoCardless offers a feature called Safer Refund Period, which blocks refunds from being initiated within 7 days of the original request. Learn more about refunds. This function will be OFF by default.
  • If you would like this feature enabled, contact your GoCardless account manager or support, and ensure that your billing flows account for the delay in payment confirmations when issuing refunds.
  1. A GoCardless invoice can be refunded a max of five times, via partial refund amounts. Beyond five refunds, GoCardless and Recurly will return an error.
  • Example, returning individual line items on an invoice can be returned, with a max of five refunds to the single invoice.
  • Refunds with Credit Invoices: Refunds that are accepted by Recurly may ultimately fail for due to the GoCardless Safer Refund feature. When this occurs, the failure will act as a gateway failure and generate a credit memo on the account. This can later be refunded externally if the intent is to provide the money back to the end customer.
  • Refunds WITHOUT Credit Invoices: Same as above, however the account will receive credits that can be consumed rather than invoices, and can be refunded externally.
  • In either case, with the 7 day Safer Refund feature is enabled, it is recommended to build that window into your refund flow as to not get into this situation.


GoCardless has a minimum ACH transaction value of $2. ACH Transactions below this minimum will decline.

1 . Mandate status tracking will be updated in a subsequent phase of this project. All information will be available in the GC dashboard in the interim

  1. The ability to import existing direct debit billing info, and the mandates associated with the accounts will be added in a subsequent phase of this project.
  2. Hosted Gift Card pages will not support paying via GoCardless. This is because the delayed nature of funding can put the merchant at risk when using direct debit as a funding source.
    Note: API endpoints will support direct debit as a funding source for gift cards. Because direct debit transactions can take days before funds are confirmed, there is risk in funding a gift card with these payment methods. Please be sure you understand this before setting up direct debit as a funding source for your gift cards.
  3. There is not an automatic retry schedule available for direct debit, for any failure type. Manual retries are available via the Recurly UI.
  4. A declined transaction on a past due invoice: when modifying the subscription by running another transaction/collection attempt, invoice will go from past_due to processing. This means unless there is something invalid about the billing info where Recurly will an immediate decline, this scenario will always succeed due to the asynchronous payment nature.

Pricing and Plans

  • GoCardless is available on Recurly Professional and Elite plans.
  • GoCardless payment volume rolls up into merchants overall TPV calculation.
  • GoCardless transaction volume count towards overall usage per plan type.