Zoho Books and GoCardless integration

What moves between them

The main flow moves customer invoice data from Zoho Books to GoCardless to set up payment collection. Customer records and payment mandates sync from Zoho to GoCardless, and payout and payment event data flows back from GoCardless into Zoho for reconciliation and AR matching. Payouts are read-only in GoCardless, so ml-connector retrieves them for reporting and matching but does not create or update them.

How ml-connector handles it

ml-connector stores both credential sets encrypted and routes every Zoho Books call to the correct regional base URL based on the region returned in the OAuth token response. It refreshes Zoho access tokens proactively at the 55-minute mark to avoid token expiry during a flow run. On the GoCardless side, it verifies every webhook payload by computing HMAC-SHA256(secret, raw_body) and comparing to the Webhook-Signature header, rejecting any mismatch with a 401 response before processing the event. Customer records are matched on email or reference number to avoid duplicate mandates. Amount fields from Zoho are converted from the organization currency to the smallest currency unit for GoCardless (pence/cents). Both systems' rate limits (Zoho: 100 req/min, GoCardless: unspecified in constraints) are respected with exponential backoff. Every record carries a full audit trail and can be replayed if a downstream call fails.

A real-world example

A mid-sized SaaS company uses Zoho Books for accounting and invoicing, and needs to collect subscription payments and AR invoices directly from European customer bank accounts. Before the integration, finance staff manually created payment mandates in GoCardless and matched incoming payouts back to Zoho invoices by hand, a process that took hours each month and created reconciliation gaps. With Zoho Books and GoCardless connected, customer records from Zoho trigger mandate setup in GoCardless, invoice-to-payment linkage is automatic, and payout confirmations sync back into Zoho. Reconciliation now runs in minutes, and payment collection is driven by the invoice workflow rather than manual setup.

What you can do

• •Sync customer records from Zoho Books to GoCardless and set up payment mandates for recurring billing and one-off invoice collection.
• •Map Zoho invoice line items to GoCardless payment requests, automatically creating collection instructions tied to the correct customer.
• •Retrieve GoCardless payout and payment events and reconcile them against Zoho invoices to close AR automatically.
• •Handle Zoho's regional base URLs, OAuth token refresh cycles, and GoCardless webhook signature verification.
• •Convert currency amounts from Zoho organization currency to the smallest currency unit (pence/cents) that GoCardless requires.

Questions

Which direction does data move between Zoho Books and GoCardless?

Customers, invoices, and payment instructions move from Zoho Books into GoCardless to set up collection. Payment and payout events flow back from GoCardless into Zoho for reconciliation and AR matching. Payouts are read-only in GoCardless, so ml-connector retrieves them for reporting but does not create or update them.

How does ml-connector handle Zoho's regional base URLs and OAuth token expiry?

ml-connector extracts the region from the OAuth token response and routes all Zoho calls to the correct regional base URL (US, EU, India, Australia, Japan, Canada, China, or Saudi Arabia). Access tokens expire after 1 hour, so ml-connector refreshes them proactively at 55 minutes to ensure no token expiry occurs mid-flow.

What happens if a GoCardless webhook signature does not verify?

ml-connector computes HMAC-SHA256 using the secret and raw request body, compares it to the Webhook-Signature header, and rejects any mismatch with a 401 response before processing the event. This prevents GoCardless from marking the endpoint as healthy and stopping retries on a bad signature.