QuickBooks Online and GoCardless integration

What moves between them

Invoices and customers flow from QuickBooks Online into GoCardless first. For each customer in QuickBooks Online, a GoCardless customer is created or updated, and for each unpaid invoice, a payment mandate and recurring subscription are created in GoCardless, so bank debit collections can begin without re-keying. Payment records and payout summaries then flow back from GoCardless into QuickBooks Online on a daily basis, matched to the original invoices by customer ID and invoice number, and posted as payment entries in the general ledger. Bank payout schedules and settlement reports keep your cash forecast aligned with actual collections.

How ml-connector handles it

ml-connector stores the QuickBooks Online OAuth 2.0 refresh token encrypted and exchanges it for a fresh access token before each request cycle. When the refresh token rotates (every 24-26 hours), the new token is captured from the response and re-encrypted before the stale token is purged - this prevents auth chain breakage if a rotation is missed. On the GoCardless side, the bearer token is stored encrypted and the webhook endpoint is registered with GoCardless to receive payment and payout events. For every webhook received, ml-connector verifies the HMAC-SHA256 signature against the raw request body and the shared webhook secret before processing - a bad signature causes the request to be rejected with no 2xx response, so GoCardless knows to retry. QuickBooks Online objects carry a SyncToken for optimistic concurrency control - if another system updates the same invoice or customer while ml-connector has a copy, the update fails with a conflict error and the latest version is fetched and retried. Unpaid invoices are polled from QuickBooks Online on a daily schedule or via webhook, and for each customer and invoice pair, ml-connector checks if a GoCardless subscription already exists to avoid creating duplicates. GoCardless payment amounts are integers in the smallest currency unit (pence, cents, etc.), and ml-connector converts from QuickBooks Online decimal amounts before posting. Every payment record is stamped with a unique external ID to prevent double-posting if a webhook is received twice.

A real-world example

A small online retail business runs QuickBooks Online for invoicing and accounting, and uses bank mandates to collect subscription fees and recurring orders from customers. Before the integration, the accounting team entered each customer and invoice manually into GoCardless when setting up collections, and at month-end they downloaded payment reports from GoCardless and re-entered totals into QuickBooks Online to reconcile their aged receivables and general ledger. With QuickBooks Online and GoCardless connected, each customer and invoice is synced automatically when created in QuickBooks Online, payment collections happen on schedule without manual setup, and payment and payout records flow back into QuickBooks Online daily so reconciliation happens automatically. The manual data entry is gone and the accounting team spends month-end close actually closing the books instead of chasing invoice and payment discrepancies.

What you can do

• •Sync unpaid invoices and customer records from QuickBooks Online into GoCardless to set up payment mandates and recurring collections without re-keying.
• •Fetch payment and payout records from GoCardless and post them into QuickBooks Online's general ledger, matched to the original invoices by customer and amount.
• •Refresh QuickBooks Online OAuth 2.0 tokens on rotation and cache them encrypted so auth chain breakage does not happen.
• •Verify GoCardless webhook signatures and reject unsigned or tampered events before posting payment data into QuickBooks Online.
• •Track every invoice, payment, and payout record with an audit trail and idempotency key to prevent duplicate postings and support dispute handling.

Questions

Which direction does data move between QuickBooks Online and GoCardless?

Invoices and customers flow from QuickBooks Online into GoCardless first so payment mandates can be set up. Payments and payouts then flow from GoCardless back into QuickBooks Online so the general ledger and aged receivables are reconciled. Payout schedules are read-only in GoCardless, so ml-connector does not write settlement records back to the payment processor.

How does the integration handle QuickBooks Online's OAuth 2.0 refresh token rotation?

QuickBooks Online refresh tokens rotate every 24-26 hours and a new token is issued in the response when the old one is exchanged. ml-connector captures the new token from the response, re-encrypts it, and purges the old one before the next request cycle. This prevents auth chain breakage if a rotation is missed or delayed.

What happens if a GoCardless webhook is received twice or the signature does not match?

Every payment record is stamped with a unique external ID to prevent double-posting if a webhook is received twice. For signature verification, ml-connector computes HMAC-SHA256 against the raw request body and compares it to the Webhook-Signature header - if the signature does not match, the request is rejected without a 2xx response so GoCardless knows to retry.