Table of Contents

GoCardless Integration: Overview & Setup

Jennifer Trower Updated by Jennifer Trower

​Read Time: 7 mins

GoCardless is a Direct Debit provider that collects payments directly from your subscribers' bank accounts. Sonar integrates with GoCardless as a bank account processor, but it works differently from other processors: subscribers authorize Direct Debit themselves through your Sonar customer portal before you can collect payments from them.

This article explains what GoCardless and Direct Debit mandates are, walks through the three parts of setup, and covers what subscribers see, how notifications and timing work, and how declined or cancelled payments are handled. It is written for administrators setting up GoCardless as a payment option.

Prerequisites

  • A GoCardless account with access to the Developers area of the GoCardless dashboard.
  • A configured Sonar customer portal. To set one up, see the Adding a Customer Portal to Your Sonar Instance article.
  • Your customer portal Settings Key, which is required to change customer portal settings.
The GoCardless integration requires Sonar's customer portal. Subscribers must log in to the portal to authorize Direct Debit and add their bank account. This cannot be done from within your Sonar instance.

Permissions

Before getting started with the feature, your user roles will need to be adjusted to account for the permissions required to use the GoCardless integration feature.

If you're a Super Admin, you already have full access and no changes are needed. To learn more, see the User Role Creation & Best Practices article.
Entity
Permission
Reason
Bank Account Processor
Create a bank account processor
Create the GoCardless bank account processor in your Sonar instance.
Account
View all account transactions
Review GoCardless payments on an account and confirm whether a payment was declined or cancelled.

What is GoCardless?

GoCardless is a Direct Debit provider that manages the full collection process on behalf of businesses. Once a subscriber authorizes Direct Debit, you can collect payments from their bank account without them initiating each payment. To learn more about GoCardless, visit the GoCardless website.

What is a Direct Debit mandate?

A Direct Debit mandate, also called a Direct Debit Instruction, is the authorization a subscriber gives you to collect payments from their bank account. You cannot collect Direct Debit payments from a subscriber until they have agreed to and signed the mandate. In Sonar, subscribers complete the mandate through your customer portal.

For more detail, see GoCardless's guide to Direct Debit mandates.

Setting Up the GoCardless Integration

Setup happens in three places, in this order:

  1. The GoCardless dashboard, where you create an access token and a webhook endpoint.
  2. Your Sonar instance, where you create the GoCardless bank account processor.
  3. Your Sonar customer portal, where you turn on GoCardless for subscribers.

Part 1: Within the GoCardless Portal

The access token lets Sonar and your customer portal communicate with GoCardless. The webhook keeps Sonar updated automatically when the status of a payment or mandate changes, such as when a payment fails or a mandate expires.

  1. Log in to the GoCardless dashboard and go to the Developers tab.
  2. Click Create in the top-right corner, then select Access token
  3. In the Create Access Token window, enter a name for the token, select Read-write access, and click Create access token.
    1. Copy the access token that appears. You will need it in Part 2 and Part 3.
      GoCardless only shows your access token once. Copy it now and store it securely, as you would a password. If you lose it, you will need to create a new token.
  4. Back on the Developers tab, click Create in the top-right corner, then select Webhook endpoint.
  5. In the Create Webhook Endpoint window, enter a name for the webhook and enter the URL in this format: your Sonar instance URL followed by /api/webhooks/gocardless/events. For example, https://yourcompany.sonar.software/api/webhooks/gocardless/events.
    Optionally, enter a passphrase in the Secret field. If you leave it blank, GoCardless generates one for you.
  6. Click Create webhook endpoint.
  7. Keep the GoCardless dashboard open, or note your access token and webhook secret somewhere secure. You will need both in Part 2.
    Can't find your webhook secret?
    On the Developers tab, select your webhook from the Webhook Endpoints table. Its details page shows the secret.


Part 2: Create the bank account processor in Sonar

  1. Within the Create Bank Account Processor window that appears, select “GoCardless (https://gocardless.com)” as the Bank Account Provider.
  2. In the Create Bank Account Processor window, select GoCardless (https://gocardless.com) as the Bank Account Provider.
  3. Enter your access token from Part 1 in the Access Token field and your webhook secret in the Webhook Endpoint Secret field.
  4. In Companies, select the companies that should use GoCardless.
  5. Check Enabled. Check Primary if GoCardless should be the default bank account processor.
  6. Click Create.
Each company can only be associated with one bank account processor. If you select a company that is already associated with another processor, it will be removed from that processor.

Part 3: Turn on GoCardless in your customer portal

  1. Go to the Settings page of your customer portal at https://[your-portal-url]/settings.
    Enter your customer portal Settings Key when prompted.
  2. Scroll to the GoCardless Integration section and turn on Enable GoCardless.
  3. Paste your access token from Part 1 and, if needed, set the currency mode.
  4. Save your changes.

Your GoCardless integration is now set up. The next section explains what your subscribers will see.

What subscribers see

Subscribers set up Direct Debit from your customer portal. After logging in, they click "Add new bank account" to add their bank account as a payment method.

The subscriber is then sent to GoCardless, where they enter their bank account details and complete the Direct Debit mandate.

After confirming their details, the subscriber sees a confirmation that Direct Debit has been set up.

GoCardless also emails the subscriber to confirm their details and explain how payments will be collected.

You will receive an email from GoCardless letting you know a new subscriber has signed up and that you can begin collecting payments from them.

In your Sonar instance, the bank account added through the customer portal is automatically set to auto pay. GoCardless transactions appear on the account as eCheck.

Notifications

Direct Debit regulations require subscribers to be notified before their account is charged. GoCardless sends these compliant email notifications automatically, so there is nothing to configure in Sonar. Subscribers who authorize Direct Debit through GoCardless receive emails when their mandate is authorized, ahead of each upcoming payment, and when a payment is made.

Payment timing

Direct Debit is not an instant payment method. Both mandates and payments take several days to process.

Payments typically take at least three working days to clear, and in most cases the subscriber must be notified before a payment can be initiated. For details, see GoCardless's Direct Debit timings guide.

Declined and cancelled payments

When a subscriber's payment is submitted through GoCardless and appears to succeed, Sonar marks it as successful. If something goes wrong after that point, GoCardless updates Sonar through the webhook you set up in Part 1.

  • Declined payments: If the subscriber's bank declines the charge, for example, because of insufficient funds, GoCardless updates the payment's successful flag in Sonar. The full decline message from GoCardless is stored but is not shown in the Sonar interface. You can retrieve it through the Sonar API using full_processor_response.
  • Chargebacks and disputes: If the subscriber initiates a chargeback or disputes the payment, GoCardless updates the payment to cancelled.

In both cases, the amount owing is restored on the account. Sonar does not notify you when this happens. If the subscriber does not submit a new payment, the difference shows up in your accounting reports and on the subscriber's next invoice.

New to the Sonar API? See the Consuming the Sonar API article to get started.

Need a hand?

Our Support Team is here to help

How did we do?

GPS Tracking Providers: Overview

Handling Static IPs with the Calix SMx Integration

Contact