GoCardless Direct Debit Integration

Overview

GoCardless is a Direct Debit payment gateway that allows your customers to set up mandates for automatic payments directly from their bank accounts. Unlike credit card gateways, GoCardless uses bank-to-bank transfers which typically have lower fees and higher success rates for recurring payments.

Key Features

• Direct Debit Mandates - Customers authorise ongoing payments from their bank account

• Hosted Setup Flow - Secure GoCardless-hosted pages for mandate creation

• Email-Based Setup - Send customers a link to set up their mandate

• Webhook Integration - Automatic payment status updates

• One-Off Payments - Charge any amount against an existing mandate

• Refund Support - Process refunds through the platform

• Multi-Currency - Supports AUD, GBP, EUR and other currencies

How GoCardless Works

1. Customer sets up a mandate - They authorise your business to collect payments from their bank account

2. Mandate is created - GoCardless verifies the bank details and creates a mandate

3. You collect payments - Charge any amount against the mandate when invoices are due

4. Payment is confirmed - GoCardless notifies Pracbill when payment succeeds or fails

Setting Up GoCardless

Prerequisites

Before you begin, you'll need:

• A GoCardless account (Sandbox for testing, Live for production)

• Your GoCardless Access Token

• Your Webhook Secret (for secure event notifications)

Step 1: Create a GoCardless Account

1. Go to gocardless.com and sign up for an account

2. Complete the verification process

3. For testing, use the Sandbox environment first

Step 2: Generate API Credentials

1. Log in to your GoCardless Dashboard

2. Navigate to Developers → Create → Access Token

3. Copy your Access Token (keep this secure!)

4. Navigate to Developers → Webhooks → Create

5. Set the webhook URL to: https://billing.pracbill.com.au/api/gocardless/webhook

6. Copy your Webhook Secret

Step 3: Configure GoCardless in Pracbill

1. Navigate to Admin → Payment Options

2. Click Add New Payment Gateway

3. Select GoCardless from the gateway list

4. Enter your configuration:

5. Click Save

Step 4: Enable Direct Debit Option

In the Payment Options configuration:

1. Check the Direct Debit option under Payment Types

2. Set any surcharges if applicable

3. Save your changes

Setting Up Customer Mandates

There are two ways to set up a Direct Debit mandate for a customer:

Method 1: Send Email Link (Recommended)

1. Navigate to the customer record

2. Go to Payment Methods tab

3. Click Add Payment Method

4. Select GoCardless as the gateway

5. Ensure Email the setup link to the customer is checked

6. Click Send Setup Email

The customer will receive an email with a secure link to complete their mandate setup on GoCardless's hosted page.

Method 2: Direct Setup Link

1. Follow steps 1-4 above

2. Uncheck the email option

3. Click Open Setup Page

4. A new tab opens with the GoCardless mandate setup page

5. Complete the setup with the customer present

What Happens After Setup

1. Customer completes the mandate setup on GoCardless

2. GoCardless sends a webhook to Pracbill

3. Pracbill automatically creates a Payment Method record

4. The mandate is now ready for payments

Taking Payments

Automatic Payments

Once a mandate is set up and marked as Primary:

1. Invoices generated for the customer will automatically attempt payment on the due date

2. GoCardless processes the Direct Debit (typically 3-5 business days)

3. Payment status is updated via webhook when confirmed or failed

Manual Payments

1. Navigate to the customer or invoice

2. Click Take Payment

3. Select the GoCardless payment method

4. Enter the amount

5. Click Process Payment

Note: Direct Debit payments are asynchronous - they show as "Pending" initially and are confirmed via webhook after bank processing.

Payment Lifecycle

Understanding the Direct Debit payment lifecycle:

Webhooks

GoCardless sends webhook events to notify Pracbill of payment and mandate status changes.

Webhook URL

Configure this URL in your GoCardless Dashboard:

Events Handled

Refunds

To refund a GoCardless payment:

1. Navigate to the payment record

2. Click Refund

3. Enter the refund amount (partial or full)

4. Confirm the refund

Refunds are processed through GoCardless and typically take 3-5 business days.

Troubleshooting

Mandate Setup Email Not Received

• Check the customer's email address is correct

• Verify the email isn't in spam/junk folder

Payment Shows Pending for Too Long

• Direct Debit payments typically take 3-5 business days

• Check the GoCardless Dashboard for payment status

• Ensure webhook URL is correctly configured and accessible

Webhook Signature Verification Failing

• Ensure the Webhook Secret in Pracbill matches GoCardless Dashboard

• Check the webhook secret hasn't been regenerated

• Verify no proxy is modifying the request body

Payment Failed

Common reasons for failed payments:

• Insufficient funds - Customer's bank account doesn't have enough funds

• Bank account closed - The bank account no longer exists

• Mandate cancelled - Customer cancelled the Direct Debit with their bank

• Invalid bank details - Bank details were incorrect

Supported Features

Further Resources

• GoCardless API Documentation

• GoCardless Help Centre

• Understanding Payment Methods

• Automated Payments Setup