QuickBooks Desktop and GoCardless integration

What moves between them

The main flow is from GoCardless into QuickBooks Desktop. When a customer payment is collected or a refund is issued, GoCardless sends a webhook event (payment.created, payment.failed, refund.created, or similar) with customer, amount, and mandate details. ml-connector receives the webhook, verifies the HMAC-SHA256 signature, and queues a ReceivePayment record for QuickBooks. On the next QBWC polling interval, ml-connector sends the queued payment to QuickBooks via SOAP, matched to the customer by mapping GoCardless customer references to QuickBooks customer entries. The reverse flow (QuickBooks invoice list to GoCardless for mandate setup or billing request creation) is optional and driven by your business rules.

How ml-connector handles it

ml-connector receives GoCardless webhook events at a registered HTTPS endpoint and verifies the Webhook-Signature header by computing HMAC-SHA256(webhook_secret, raw_event_body) and comparing the result. Valid events are enqueued with customer ID, payment amount in the correct currency unit, and reference data. When QBWC polls at your configured interval, ml-connector converts each queued payment into a QuickBooks ReceivePayment QBXML request, authenticates with the QBWC SOAP session-token handshake (taking the username and password QBWC provides and returning a GUID session ticket), and sends the request over HTTPS. Payments are matched to QuickBooks customers by mapping GoCardless customer external IDs or names to QuickBooks customer names or custom fields, and amounts are converted from GoCardless' smallest-unit integer to QuickBooks decimal format. Failed or blocked GoCardless collections are received as payment.failed events and can be logged or flagged in QuickBooks as memos on a pending ReceivePayment record. Each payment is tracked with an audit trail including the GoCardless event ID, QuickBooks TxnID, and any edit conflicts so retries can be cleanly replayed.

A real-world example

A B2B software-as-a-service company with 300 paying customers in the UK and Europe uses QuickBooks Desktop at their London office for invoicing and accounts receivable. They switched to GoCardless to collect recurring subscription payments directly from customer bank accounts, replacing monthly manual bank transfers and invoice reminders. Before the integration, the finance team received a daily bank reconciliation file and spent 2 to 3 hours each morning matching payments to customer invoices, creating ReceivePayment records in QuickBooks, and investigating payment failures by hand. With QuickBooks Desktop and GoCardless connected, each collection shows in QuickBooks within minutes of the webhook arriving, AR aging is current by 9 AM, and collection failures trigger an alert so the team can follow up the same day instead of discovering problems at month-end close.

What you can do

• •Record GoCardless payments and refunds as ReceivePayment entries in QuickBooks Desktop, matched to the correct customer and invoice.
• •Verify GoCardless webhook signatures (HMAC-SHA256) and filter failed or incomplete payments to avoid duplicate AR entries.
• •Authenticate through QuickBooks QBWC using the session-token handshake on every polling interval.
• •Handle failed payment events and payment.failed webhooks to flag collection issues in QuickBooks for follow-up.
• •Convert GoCardless amount fields (smallest currency unit) to QuickBooks decimal format and track every payment with a full audit trail.

Questions

How does ml-connector handle the QuickBooks SOAP session-token authentication?

ml-connector receives the username and password that QBWC provides during the SOAP authenticate() call and returns a GUID session ticket. That ticket is used for all subsequent QBXML requests (ReceivePayment queries and adds) during that polling session. The session is stateless per poll interval, so a new ticket is issued on the next QBWC callback.

What happens if a GoCardless webhook signature fails verification?

ml-connector rejects the event and returns HTTP 400 Bad Request without creating any QuickBooks record. This prevents unauthorized or tampered events from creating false payments. The event is logged for audit and investigation, and your operations team is alerted.

How are customers matched between GoCardless and QuickBooks?

ml-connector matches customers by mapping GoCardless customer IDs to QuickBooks customer names or custom fields (e.g., storing the GoCardless customer reference in a QuickBooks custom field). If a customer does not exist in QuickBooks, the payment is held in a queue with a note so you can resolve the mismatch before the next polling interval.