Configure GoCardless integration

Overview

Integrating GoCardless with gaiia lets your customers pay their invoices by Direct Debit from their bank account. GoCardless supports bank payments only. Use the Stripe integration for credit cards.

The Direct Debit scheme depends on your billing country and currency. You do not choose it:

Customers enter their bank details on a GoCardless page, not in gaiia. gaiia never sees or stores their account numbers.

BACS Direct Debit is also available through Stripe. See Enable bank payments for Stripe.

This article covers the GoCardless prerequisites, where to find your access token and webhook secret, how to set up the integration in gaiia, and what happens when a payment fails.

Before you start

Bank payments are delayed payment methods. After a payment is submitted, it stays "Pending" in gaiia until GoCardless confirms whether it succeeded, which can take several business days. A new bank account payment method is also "Pending" until GoCardless confirms the mandate.

Before you set up the integration, make sure that:

1. You have a GoCardless account for each environment you want to connect. That means a sandbox account for testing and a live account for production.
2. For BACS, your GoCardless creditor is activated for BACS and has a Service User Number. Activation is done with GoCardless and can take some time, so start it early.
3. For BACS, your payout bank account can receive Bacs Faster Payments (UK bank account) or Bacs International (non-UK bank account).
4. The currency in your gaiia billing settings matches the scheme: GBP for BACS, CAD for PAD. GoCardless rejects a mandate whose currency does not match its scheme.

Do not change your GoCardless scheme identifier or turn on a GoCardless add-on that changes the merchant name on your customers' bank statements without contacting gaiia Support first. For BACS, this change gives every mandate a new ID, and gaiia does not yet pick up the new ID automatically. Collections on the affected mandates stop until it is fixed.

Steps

The setup has four parts. You will go back and forth between GoCardless and gaiia, because gaiia gives you the webhook URL and GoCardless gives you the webhook secret. Keep both open.

A. Create your access token in GoCardless

1. Sign in to your GoCardless dashboard.
2. Open Developers, then click Create and select Access token.
3. Give the token a name you will recognize, for example "gaiia".
4. Set the scope to Read-write access.
5. Copy the token and keep it somewhere safe. GoCardless shows it only once.

B. Copy your webhook URL from gaiia

1. In gaiia, navigate to Settings > Integrations.
2. Open the App directory tab, search for GoCardless and click the Install button.
   
3. Click Add configuration.
   

4. Copy the Webhook URL shown at the top of the configuration with the copy icon next to it.

   The URL is unique to this configuration. Do not leave the page before you click Connect in part D, or you will need to copy the new URL that gaiia generates.

C. Create the webhook in GoCardless

gaiia uses GoCardless webhooks to learn when mandates become active and when payments succeed or fail. Without the webhook, payments stay "Pending" in gaiia.

1. In your GoCardless dashboard, open Developers, then click Create and select Webhook endpoint.
2. Give the endpoint a name, for example "gaiia".
3. Paste the Webhook URL you copied in part B.
4. Click Create webhook endpoint.
5. Copy the Secret shown for the new endpoint. This is the webhook secret you will enter in gaiia.

Do not point a GoCardless sandbox webhook at a production configuration in gaiia. Each configuration has its own webhook URL, so create one webhook endpoint per configuration.

D. Finish the configuration in gaiia

1. Back in gaiia, fill in the configuration fields using the table below.
   
2. To connect a sandbox account as well, click Add configuration again and repeat parts A to C with your GoCardless sandbox account.
3. Click the Connect button.

Scroll right to view the whole table on smaller screens.

Choosing a mandate setup mechanism

Both mechanisms send the customer to a GoCardless page where they enter their own bank details and give consent. The customer sees almost no difference. The differences are in what happens around that page:

We recommend Billing request flow. It is the mechanism GoCardless continues to develop, and it keeps abandoned checkouts recoverable.

1. Mandates that already exist keep working when you switch mechanisms. Nothing needs to be migrated.
2. You can switch back at any time. A customer who already received a setup link can still finish with it.
3. Turning on Billing request flow also gives your agents the option to send a setup invitation. There is no separate setting for it.
4. The setup invitation is sent by email only, to the account's registered contact. It cannot be sent to archived, commercial or billing-only accounts.
5. Setup links do not expire in gaiia. A bank account payment method whose setup is never finished stays "Pending".

When a payment fails

When GoCardless reports a failed payment, gaiia marks it "Failed" and uses your bank account retry settings to decide whether to try again.

For BACS, the bank reports a reason code that starts with ARUDD-. gaiia only retries ARUDD-0 ("refer to payer"), which is almost always insufficient funds. Every other ARUDD code is final: the mandate or bank account can no longer be charged, so retrying would fail again. When a BACS payment fails with another code, contact the customer to set up a new bank account payment method.

For PAD, gaiia retries failures that GoCardless reports as insufficient funds or "refer to payer".