Wave Accounting and GoCardless integration

What moves between them

Customers and invoices flow from Wave into GoCardless. When a new customer is added to Wave, ml-connector creates a GoCardless customer and associated bank account mandate. When an invoice is issued in Wave, a corresponding billing request or subscription is initiated in GoCardless. Payment events from GoCardless flow back to Wave as transaction records, matched to the invoices they satisfy. The reconciliation is one-way for postings: GoCardless webhooks trigger Wave payment creation and invoice closure, while Wave's invoice state drives mandate and billing request setup on the GoCardless side.

How ml-connector handles it

ml-connector maintains separate credential sets: Wave OAuth 2.0 refresh tokens stored encrypted with auto-renewal when access tokens expire within 30 minutes, and GoCardless bearer tokens also encrypted. It subscribes to both Wave webhooks (invoice, payment, customer events) and GoCardless payment webhooks. When a Wave customer is created, ml-connector posts a new GoCardless customer and attaches their provided bank account as a mandate. When a Wave invoice transitions to approved or sent, ml-connector checks whether a GoCardless billing request or subscription exists for that customer; if not, it creates one with terms matching the invoice total and due date. GoCardless payment webhooks trigger the reverse: ml-connector reads the payment status (pending, paid, failed) and posts a Wave transaction against accounts receivable, matched to the invoice by customer and amount. Webhook signature verification is mandatory on both sides (HMAC-SHA256 with x-wave-signature and Webhook-Signature headers respectively, 5-minute replay window for Wave). Because Wave invoices cannot be patched in-place, payment flows create new transactions; Wave's transaction model handles the ledger entry. GoCardless payouts are read-only, so ml-connector uses payout events only for reconciliation reporting. All records carry full provenance: invoice IDs, mandate IDs, payment references, and batch timestamps.

A real-world example

A small SaaS business runs on Wave Accounting for invoicing and AR. Their customers are distributed across the UK and Europe, and many prefer to pay via bank debit rather than card. Before the integration, the finance team issued invoices in Wave, manually created corresponding mandates in GoCardless, monitored payment status in the GoCardless dashboard, and re-entered successful payments back into Wave as transactions - a manual cycle that delayed AR reporting and introduced typos. With Wave and GoCardless connected, each new customer flows to GoCardless with one API call, invoices auto-generate payment requests tied to the right mandate, and collections post back to Wave's AR immediately when the bank releases them. The finance team now sees a single source of truth: Wave invoices and their payment status, with no manual re-keying.

What you can do

• •Sync Wave customers to GoCardless bank account mandates when customers are created or updated.
• •Create GoCardless billing requests and subscriptions tied to Wave invoices, with terms matching invoice amounts and due dates.
• •Post GoCardless payment events back to Wave as transaction records, matched to the correct invoices and accounts receivable.
• •Verify webhook signatures on both Wave (HMAC-SHA256, x-wave-signature header) and GoCardless (HMAC-SHA256, Webhook-Signature header) to ensure data authenticity.
• •Handle Wave OAuth 2.0 token refresh automatically and store both Wave and GoCardless credentials encrypted, with a full audit trail on every reconciliation.

Questions

Which direction does data move between Wave and GoCardless?

Primarily customer-to-bank-account and invoice-to-mandate flow from Wave to GoCardless on setup. Payment and collection events flow from GoCardless back to Wave as transaction postings to close out invoices. Reference data is synchronized bidirectionally so Wave customers and GoCardless mandates remain aligned. Wave invoices are read-only after approval, so ml-connector does not write back to Wave invoice details.

What happens when a GoCardless payment fails or is pending?

ml-connector receives the payment webhook from GoCardless showing the status (pending, paid, failed, cancelled). For paid payments, it immediately posts a Wave transaction to accounts receivable, matched to the invoice by customer and amount. For pending or failed payments, ml-connector logs the event and updates a reconciliation record so the finance team can follow up in Wave without duplicating the record.

Do Wave and GoCardless credentials need special setup?

Yes. Wave requires OAuth 2.0 Authorization Code Flow and the connected business must have an active Wave Pro subscription; ml-connector refreshes access tokens automatically when they near expiry. GoCardless requires a bearer token from the merchant dashboard or an OAuth flow if using a partner platform. Both credentials are encrypted at rest. Webhook signature verification is mandatory on both sides to ensure authenticity.