GoCardless API Integration: A Complete Guide for UK Businesses

The GoCardless API gives UK businesses programmatic access to Direct Debit collection and open banking payments — creating mandates, scheduling payments, collecting variable amounts, handling webhook events and automating the entire payment lifecycle without anyone manually managing GoCardless. For any business collecting recurring payments, membership fees, subscription charges or B2B invoice payments, a custom GoCardless integration removes the manual work entirely. This guide covers how the API works, what it automates, and what a well-built integration looks like.

What GoCardless actually is

GoCardless is a payment processor that specialises in bank-to-bank payments — primarily Bacs Direct Debit in the UK, with SEPA Direct Debit for Europe and ACH for the US. It’s fundamentally different from Stripe or PayPal, which process card payments. GoCardless takes money directly from a customer’s bank account, with the customer’s authorisation through a Direct Debit mandate.

The key characteristics that make GoCardless attractive for recurring billing: no chargebacks (unlike card payments), lower transaction fees than cards at scale, no card expiry to manage, and the ability to collect variable amounts against an existing mandate without requiring fresh authorisation from the customer each time. Once a customer authorises a Direct Debit mandate, you can collect any amount against it — invoice amounts, usage charges, ad hoc fees — with appropriate advance notice.

GoCardless also offers Instant Bank Pay, their open banking product, which enables immediate one-off bank transfers rather than the 3–5 day processing window of traditional Direct Debit. This opens up use cases where the delayed settlement of Bacs doesn’t work — deposits, one-time purchases, immediate access provisioning on payment.

How GoCardless API authentication works

The GoCardless API uses access token authentication — simpler than the OAuth flows required by Xero or the Azure OAuth used by DVSA. You create an account, register an application in the GoCardless developer dashboard, and receive an access token. This token is included as a Bearer token in the header of every API request.

GoCardless has separate environments: sandbox for development and testing, and live for production. Each environment has its own access token. All development and testing happens in the sandbox — it returns realistic responses, processes test mandates and payments, and fires webhook events exactly as the live environment does. Switching from sandbox to live is a matter of changing the access token and the API endpoint URL.

The token must be stored server-side and never exposed in client-facing code. All GoCardless API calls go through a server-side proxy — your platform sends a request to your own server, the server calls the GoCardless API, and the result is returned. This protects your credentials and keeps all payment processing logic server-side where it belongs.

The GoCardless payment flow

Understanding the GoCardless payment flow is important for building an integration that handles all states correctly. Unlike card payments which are either approved or declined immediately, Bacs Direct Debit has a multi-day processing window with distinct states.

Mandate creation. The customer completes a Direct Debit mandate authorisation — either through GoCardless’s hosted mandate page or through a custom-built mandate flow embedded in your platform. Once authorised, GoCardless returns a mandate ID that you store against the customer record. The mandate is now active and can be used to collect payments.

Payment creation. When you want to collect a payment, you create a payment object against the mandate: amount, currency, and optionally a charge date. GoCardless validates the mandate and schedules the payment. The payment moves through several states: pending submission, submitted, confirmed, paid out. Each state change fires a webhook event.

Processing window. Bacs payments take 3–5 working days to process. A payment created on Monday typically confirms on Wednesday or Thursday. Your integration needs to handle this window correctly — not provisioning access until payment is confirmed, not marking an invoice paid until the payment has settled.

Failed payments. If a Direct Debit payment fails — insufficient funds, mandate cancelled, bank account closed — GoCardless fires a payment failed webhook event with a failure reason. Your integration handles this: retrying on your defined schedule, notifying the customer, suspending access if the payment remains uncollected after retries are exhausted.

Payouts. GoCardless pays collected funds to your bank account on a daily or weekly schedule (depending on your plan). Each payout event is also available via webhook, useful for reconciliation with Xero or your accounting system.

Direct Debit vs Instant Bank Pay

GoCardless offers two distinct payment mechanisms through the same API, and understanding when to use each is important for designing the right integration.

Bacs Direct Debit is the right choice for recurring billing — subscriptions, membership fees, regular invoice collection. The 3–5 day processing window is acceptable for recurring charges because the payment is scheduled in advance. Lower fees, no chargebacks, no card expiry management, and variable amounts without re-authorisation make it the best mechanism for businesses billing customers regularly.

Instant Bank Pay (GoCardless’s open banking product) is the right choice for one-off payments where immediate confirmation matters. A deposit that needs to confirm before work starts. A one-time purchase where access should be granted immediately on payment. A failed Direct Debit that needs immediate recovery. Instant Bank Pay uses open banking rails — the customer authenticates with their bank and the payment confirms in seconds rather than days.

For businesses that need both — recurring billing via Direct Debit with occasional one-off charges or immediate recovery payments via Instant Bank Pay — the GoCardless API handles both from the same integration. A hybrid billing system using both mechanisms is the most powerful use of GoCardless’s platform.

Webhook handling

GoCardless communicates payment events to your system via webhooks — HTTP POST requests to an endpoint on your server containing event data. Every significant payment event fires a webhook: mandate created, mandate cancelled, payment confirmed, payment failed, payment paid out, refund created.

A well-built integration handles each relevant webhook event explicitly. Payment confirmed triggers invoice marking-paid and confirmation email to the customer. Payment failed triggers the retry logic and customer notification. Mandate cancelled triggers an alert to your team and a customer communication flow. Payout created triggers the accounting reconciliation.

Webhook signature verification is non-negotiable. GoCardless signs every webhook with a secret you configure. The integration verifies this signature on every incoming webhook before processing the event — rejecting any request that isn’t genuinely from GoCardless. Processing unverified webhooks is a security risk.

For the full service details and pricing, see the GoCardless API integration service. For how GoCardless compares with Stripe, see GoCardless vs Stripe. For connecting GoCardless with Xero, see GoCardless and Xero integration. For what the build costs, see the GoCardless API integration cost guide.

Related posts

• GoCardless Direct Debit for subscription billing
• GoCardless vs Stripe: which is right for your business?
• GoCardless and Xero integration
• GoCardless API integration cost

Error handling and resilience

A production GoCardless integration needs to handle failure states gracefully. The GoCardless API can return validation errors, rate limit responses, or be temporarily unavailable. Mandates can be cancelled unexpectedly by the customer’s bank. Payments can fail for any number of reasons. Each failure scenario needs a defined handler.

Mandate cancellation. A customer can cancel their Direct Debit mandate directly with their bank at any time, without notifying you. GoCardless fires a mandate cancelled webhook event when this happens. The integration catches this event, flags the customer account, stops attempting to collect against the cancelled mandate, and triggers a customer communication flow to get a new mandate in place. Without explicit handling, attempted collections against a cancelled mandate will fail indefinitely.

Payment failures with retry logic. GoCardless’s Smart Retries feature can automatically retry failed payments, but for integrations with custom access control logic — SaaS platforms suspending access on non-payment, for example — you need to define the retry schedule in your own code. A typical pattern: retry after 3 days, retry again after 7 days, then mark the account for manual follow-up. Each retry attempt notifies the customer with increasingly urgent messaging.

Idempotency. GoCardless supports idempotency keys on payment creation requests. Including a unique idempotency key per payment prevents duplicate payments if a request is retried due to a network timeout. For billing systems where a timeout could otherwise result in a customer being charged twice, idempotency keys are essential.

Testing in the GoCardless sandbox

GoCardless provides a full sandbox environment with test bank accounts, scenario-specific test sort codes and account numbers that trigger specific outcomes. There are test credentials that simulate immediate payment confirmation, others that simulate payment failure, and others that simulate mandate cancellation. This allows thorough end-to-end testing of all payment scenarios before going live.

Testing should cover: successful mandate creation, payment confirmation, payment failure and retry, mandate cancellation, refund creation, and payout events. Each scenario should verify that the correct webhook is received, processed correctly, and the right action is taken in your system. A complete test suite in sandbox means the go-live is low-risk and the integration behaves predictably in production.

If you need help with a custom API integration for your website or business application, I can help. I build bespoke API integrations for UK businesses. See API integration pricing or get in touch to discuss your project.