Xero and GoCardless integration

What moves between them

The flow runs from Xero into GoCardless and back to Xero. When an invoice is created or marked ready for payment in Xero, ml-connector reads the invoice, customer contact, and payment terms, then creates or updates a GoCardless mandate and customer bank account record if one does not already exist. GoCardless then processes the bank debit on the agreed schedule. As payments succeed, fail, or remain pending, GoCardless publishes webhook events that ml-connector receives, verifies, and translates into payment records, payment failures, or adjustment notes in Xero. The direction is primarily Xero -> GoCardless for customer and invoice metadata, and GoCardless -> Xero for collection status and reconciliation.

How ml-connector handles it

ml-connector stores both the Xero OAuth2 refresh token and the GoCardless bearer token encrypted and refreshes the Xero token before it expires every 30 minutes. On the GoCardless side it validates every incoming webhook using the HMAC-SHA256 signature and the shared webhook secret, rejecting any webhook with an invalid signature (returning 401 rather than 200, since GoCardless marks endpoints with 200 responses as healthy and stops retrying failed deliveries). For each invoice ready for payment in Xero, ml-connector first checks whether a GoCardless customer and mandate already exist by matching on email address and bank account identifier, and creates them only if needed, avoiding duplicate mandates on the same bank account. Amount fields sent to GoCardless are converted from Xero's decimal format to integers in the smallest currency unit. Payment collections flow back as GoCardless webhook events, which ml-connector parses to determine success or failure, then creates corresponding payment records or notes in Xero linked to the original invoice. Every webhook delivery and API call is logged with full request and response bodies for debugging, and failed deliveries are retried with exponential backoff up to a configurable limit.

A real-world example

A small professional services firm invoices clients monthly for consulting work and retainer fees using Xero. Clients are scattered across two countries, and the firm previously sent invoices and manually followed up via email when payment did not arrive, often waiting 30-45 days past invoice date. With Xero and GoCardless connected, invoices created in Xero automatically set up a bank debit collection mandate with each client (leveraging existing bank account details stored in customer records), and GoCardless collects the payment on a schedule defined in the invoice due date. The firm's accountant sees payment status updates flow directly into Xero, so the accounts receivable aging list stays current and collection failures surface as soon as they occur, enabling faster follow-up. Month-end reconciliation is simplified because payments recorded in Xero match the GoCardless settlement report without manual re-entry.

What you can do

• •Sync Xero invoices and customer records to GoCardless, creating or updating customer accounts and payment mandates automatically.
• •Collect payments from customer bank accounts via GoCardless, with collection status syncing back to Xero as payment records or exceptions.
• •Verify GoCardless webhook signatures using HMAC-SHA256 to ensure data integrity and reject unsigned or tampered events.
• •Handle OAuth2 token refresh for Xero and maintain secure encrypted storage of both Xero and GoCardless credentials.
• •Maintain a full audit trail of every invoice synced, mandate created, collection attempted, and payment reconciliation, with replay capability for failed workflows.

Questions

What records move from Xero to GoCardless, and what comes back?

Xero invoices, contacts, and customer bank account information move to GoCardless to set up or update payment mandates and customer records. Collection status events flow from GoCardless back to Xero as payment records (on success), payment exceptions, or adjustment notes (on failure or pending status). Invoices themselves do not return to Xero; GoCardless payouts are read-only and do not flow to Xero.

How does the integration handle webhook security on the GoCardless side?

Every webhook from GoCardless carries an HMAC-SHA256 signature in the Webhook-Signature header. ml-connector computes the signature using the webhook secret and the raw request body, compares it to the header value, and returns 401 if they do not match. This is critical because returning 200 on an invalid signature causes GoCardless to mark the endpoint as healthy and stop retrying, masking real delivery failures.

What happens if a payment collection fails or is pending in GoCardless?

GoCardless publishes webhook events for payment failures and pending status changes. ml-connector receives these events, verifies the signature, and creates a payment failure note or pending payment record in Xero linked to the original invoice, so the accounting team sees the status without needing to check GoCardless separately. Failed collections can then be retried manually or reassigned to a different mandate.