FreshBooks and GoCardless integration

What moves between them

Data flows in both directions. FreshBooks invoices and clients are read via REST and matched to GoCardless customers and subscriptions; invoice due dates and amounts become payment mandate requests in GoCardless. GoCardless payments and payouts are received via webhook (or polled if webhooks are unavailable), mapped to FreshBooks invoice numbers via mandate metadata, and recorded as payment journal entries to close AR. Payout summaries also flow back to FreshBooks for cash-flow tracking. The cadence is event-driven: invoice creates trigger mandate setup; payment confirms close invoices; payout notifications update cash forecasts.

How ml-connector handles it

ml-connector stores the FreshBooks OAuth token (granted by the user via Authorization Code flow) and the GoCardless bearer token, both encrypted at rest. It listens to incoming FreshBooks webhooks for new invoices and client changes, and GoCardless webhooks for payments and payouts. On invoice create from FreshBooks, ml-connector looks up the customer in GoCardless by matching email or reference metadata, retrieves their active mandate(s), and creates a new payment request (via billing_request or direct payment API call) with the invoice amount and due date as parameters. When GoCardless delivers a payment success event, ml-connector posts the payment back to FreshBooks as a payment journal entry, mapping the GoCardless mandate ID to the original FreshBooks invoice ID via stored transaction metadata. Payout events from GoCardless are polled daily or on webhook delivery to track cleared funds. Idempotency is enforced by GoCardless idempotency-key headers and FreshBooks entity IDs; ml-connector tracks processed event IDs to prevent double-posting. Rate limits on both sides (GoCardless per IP/endpoint, FreshBooks per OAuth scope) are handled with exponential backoff and jitter. Webhook signature validation is mandatory on both sides: HMAC-SHA256 for FreshBooks (X-FreshBooks-Hmac-SHA256 header) and GoCardless (Webhook-Signature header), with mismatched signatures rejected 401. A full audit log tracks every webhook received, every payment created, every reconciliation attempt, and any mapping mismatches so month-end AR review is deterministic.

A real-world example

A professional services firm uses FreshBooks to invoice clients monthly and track expenses. They use GoCardless to collect recurring retainer fees via customer bank mandates in the UK and EU. Before the integration, the finance team manually reviewed FreshBooks invoices each week, searched for matching payment records in the GoCardless dashboard, and updated invoice status to Paid by hand, often days after payment had cleared. With FreshBooks and GoCardless connected, each new invoice automatically creates a payment request in GoCardless if the client has an active mandate; payments that arrive are logged as FreshBooks payments in near real-time, closing the invoice and feeding the payout schedule into their cash-flow forecast. Month-end reconciliation now shows AR closure automatically instead of requiring a manual hunt through two dashboards.

What you can do

• •Map FreshBooks invoices to GoCardless customers and active payment mandates, creating payment requests on invoice create.
• •Receive GoCardless payments and payouts via webhook, matching them to FreshBooks invoices and recording them as paid in AR.
• •Store both OAuth tokens (FreshBooks) and bearer tokens (GoCardless) encrypted, refreshing or validating them on each request.
• •Validate webhook signatures using HMAC-SHA256 on both FreshBooks (X-FreshBooks-Hmac-SHA256) and GoCardless (Webhook-Signature) headers.
• •Maintain a full audit log of every invoice-mandate link, every payment received, and every payout cleared, with deterministic month-end AR reconciliation.

Questions

How does ml-connector match FreshBooks invoices to GoCardless mandates?

ml-connector looks up the invoice client in FreshBooks by email or internal ID, retrieves the matching customer record in GoCardless using the same identifier or email, and checks for active mandates on that customer. If a mandate exists and the invoice amount fits the mandate limits, it creates a payment request in GoCardless. If no mandate exists, ml-connector can flag the invoice for manual setup or pause the sync.

Does ml-connector handle webhooks from both systems or does it need to poll?

ml-connector listens to webhooks from both FreshBooks and GoCardless for real-time event delivery (invoice/payment/payout create, update, and delete). Both systems support webhook delivery with HMAC-SHA256 signature verification, so ml-connector validates signatures on all inbound events. If a webhook fails or is not configured, ml-connector can poll the /events endpoint on GoCardless and the REST invoice/payment endpoints on FreshBooks, though polling is not real-time.

What happens if a GoCardless payment arrives for an invoice that does not exist in FreshBooks?

ml-connector validates the invoice ID from the mandate metadata before recording the payment. If the invoice is not found, the payment is logged in the audit trail with a reconciliation flag, and the finance team is notified so the manual payout record can be created or the mandate can be updated. This prevents unmatched payments from silently closing invoices.