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    

GoCardless

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 maximums, which can vary based on payment method. Please make sure these are inline with your business needs. https://gocardless.com/faq/merchants/

Supported Payment Methods

  • SEPA
  • ACH

Recurly integration details

SEPA and ACH are currently available via HPP, RJS, client libraries and API V2 and V3

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.

Recurly Configuration

  1. Configure your GoCardless payment gateway within Recurly.
    • Ensure that EURO is enabled for your site, by completing within Recurly under: Configuration/Currency.
    • If you do not see GoCardless as a gateway option, please contact [email protected] to enable it for you.
  2. Recurly Plans:
    • Be sure the relevant currencies are enabled for your plan. SEPA - EUR, ACH - USD.
         To do this:  Recurly - Configuration - Currencies - enable relevant currencies
      
  3. Hosted Page configuration: (Optional)
    • Enable both Hosted Payment Pages, and Hosted Account Management Pages in your ‘Hosted Pages’ configuration.
  4. Emails:
    • There are specific notifications required by SEPA to inform your customers that a payment will be collected, specifically the SEPA Pre-Renewal email template. Learn more.
    • Ensure that you have notification emails configured to be sent with as much advance notice as required by your business for SEPA transactions. The minimum notification period is 3 days.
  5. 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.

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 IBAN bank details (SEPA), account_number and routing_number (ACH) within the billing_info. Learn more.
  2. API V2 supports sending IBAN bank details (SEPA) and account_number and routing_number (ACH) within the billing_info. Learn more.
  3. Recurly.js supports sending tokenized bank account (both SEPA and ACH) information to Recurly. Note: be sure you are using Recurly.js 4 to have bank account fields available. Learn more about Recurly.js.

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.
  2. 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.
  3. 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.
  4. Example, returning individual line items on an invoice can be returned, with a max of five refunds to the single invoice.
  5. 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.
  6. 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.
  7. 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.

Limitations

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.

Subsequent phases

The Recurly Payments team is hard at work implementing BACS as our next GoCardless direct debit payment method. We plan to release this feature in Q2 20202.

More details and documentation will be available in 2020 as development progresses.

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.

Updated 5 days ago

GoCardless


GoCardless gateway integration documentation, configuration, implementation.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.