Zoho Books and Square integration

What moves between them

The main flow is Square into Zoho Books. When a Square payment is created or updated, ml-connector reads the payment details and posts them into Zoho Books as a customer payment against the matching invoice, along with a journal entry to the income account. Refunds follow the same path. Order and inventory data can be read from Square and synced to Zoho Books as line items and customer records for invoicing. The direction is primarily one-way because Zoho Books is the accounting system of record; invoice changes in Zoho Books are not written back to Square.

How ml-connector handles it

ml-connector stores both credential sets encrypted and routes all Zoho Books API calls to the correct regional base URL determined by the customer's organization region, resolving the organization ID once after login and caching it for the session. It handles Zoho Books' OAuth2 refresh-token flow by proactively refreshing at 55 minutes to avoid token expiry mid-flow. Square webhook events trigger the sync; ml-connector verifies the HMAC-SHA256 signature on every Square webhook. When a Square payment arrives, ml-connector looks up the matching Zoho Books customer and invoice, creates a customer payment record in Zoho Books, and optionally posts a journal entry to record cash receipts. Both systems are write-once for financial records, so ml-connector never mutates a posted transaction. Rate limits are managed per system: Zoho Books returns HTTP 429 at 100 requests per minute, and ml-connector backs off; Square rate limits are higher. Every record carries a jobId for deduplication across retries.

A real-world example

A small retail business uses Square for point-of-sale and online payments, and Zoho Books for invoicing and accounting. Before the integration, the owner manually exported payment reports from Square each day and entered them into Zoho Books as customer payments and deposits, a tedious task that delayed month-end close by days while payment and accounting entries were reconciled. With Square and Zoho Books connected, each payment flows into Zoho Books automatically with the correct customer and invoice reference, the deposit balance is known in real time, and month-end close is cleaner because the cash accounts are already current.

What you can do

• •Post Square payments and refunds into Zoho Books as customer payments and journal entries on the correct income accounts.
• •Route all Zoho Books API calls to the correct regional base URL and manage multi-region organizations.
• •Handle Zoho Books OAuth2 refresh tokens proactively before expiry and resolve the organization ID once per session.
• •Verify Square webhook signatures with HMAC-SHA256 and Zoho Books webhook signatures with custom HMAC verification.
• •Deduplicate payments across retries using BullMQ jobId and track payment status changes in a full audit trail.

Questions

How does ml-connector handle Zoho Books regional routing?

Zoho Books base URLs vary by customer region (US, EU, India, Australia, Japan, Canada, China, Saudi Arabia). ml-connector stores the correct regional URL in the credential set, routes all API calls through it, and resolves the organization ID once after authentication so every subsequent call includes the correct organization parameter.

Which direction do payments flow between Square and Zoho Books?

Payments flow primarily from Square into Zoho Books. When a Square payment is created or refunded, ml-connector posts it to Zoho Books as a customer payment and a journal entry on the income account. Invoice changes in Zoho Books are not written back to Square because Zoho Books is the accounting system of record.

What happens if a Zoho Books access token or Square webhook signature is invalid?

Zoho Books access tokens expire after 1 hour; ml-connector refreshes proactively at 55 minutes using the refresh token. Square webhook signatures are verified with HMAC-SHA256 on every request and rejected if they do not match. Invalid signatures return 401 so the webhook is not marked as healthy in Square.