Wave Accounting and Square integration

What moves between them

Customer and invoice records flow from Wave into Square. When a customer is created or updated in Wave, ml-connector syncs those changes to Square's customer list. Invoices created in Wave are replicated into Square as reference records, and payment events from Square are matched back to Wave invoices to keep the payment status current. Both systems emit webhooks; ml-connector listens for customer, invoice, and payment changes and propagates updates in real time where possible, supplemented by scheduled syncs to catch any missed events.

How ml-connector handles it

ml-connector stores both OAuth credentials encrypted and manages token refresh for each system independently: Wave tokens refresh every 2 hours, and Square tokens refresh every 30 days. Wave's GraphQL API is queried for customer and invoice data, while Square's REST endpoints receive the replicated records. Both systems' webhooks are registered and monitored; ml-connector validates each webhook signature (HMAC-SHA256 for Square, HMAC-SHA256 for Wave) and processes signed events within the signature window (Wave uses a 5-minute replay window). Because Wave invoices are immutable after creation, updates are handled as new snapshots rather than patches. Square customer records are looked up before insert to avoid duplicates. Every record carries a unique ID mapping and audit trail, so disputes or failed syncs can be investigated and replayed.

A real-world example

A small digital services agency bills clients through Wave Accounting, recording hours and fixed-fee projects as invoices. The same clients often place repeat orders through Square Point of Sale or Square Online. Before integration, the office manager manually entered customer details from Wave into Square and had to cross-check invoice numbers when payments came through Square. With Wave and Square connected, new customers added in Wave appear immediately in Square, invoices flow from Wave to Square for reference, and payment confirmations from Square are logged against the corresponding Wave invoices. The bookkeeper can now run a daily reconciliation by comparing Wave invoice totals to Square payment receipts without re-keying.

What you can do

• •Sync Wave customers into Square automatically when created or updated, eliminating duplicate customer entry.
• •Replicate Wave invoices to Square as reference records, keeping both systems aware of issued invoices.
• •Map Square payments back to Wave invoices to track payment status across both platforms.
• •Validate and process incoming webhooks from both Wave and Square, with automatic signature verification and replay-attack protection.
• •Maintain a full audit trail of every customer and invoice sync, with the ability to inspect, replay, and troubleshoot failures.

Questions

Which direction does data flow between Wave and Square?

Customers and invoices flow from Wave into Square. Payment records from Square are matched back to Wave invoices to track payment status. This one-way-plus-feedback model keeps Wave as the source of truth for billing while Square serves as the payment and point-of-sale record.

How does ml-connector handle Wave's immutable invoices?

Wave invoices cannot be patched after creation; they can only be approved, sent, or deleted. ml-connector treats each invoice update as a new snapshot rather than an incremental change. If an invoice is withdrawn, ml-connector records that state change in the audit trail.

Do I need to register Wave and Square webhooks manually?

ml-connector can be configured to register webhooks in both systems, or you can register them through each platform's admin dashboard. Once registered, ml-connector listens on a secure endpoint, validates signatures (HMAC-SHA256), and processes events in real time. A scheduled sync runs as a backup to catch any missed webhook deliveries.