Microsoft Dynamics 365 Business Central and Square integration

What moves between them

Sales activity moves from Square into Business Central. Completed Square payments and orders become posted sales invoices in Business Central, and the matching settlement becomes a customer payment journal line applied to that invoice. New or updated Square customers create or update Business Central customers. Reference data moves the other way: Business Central items and customers can be written to the Square catalog and customer list so the storefront and the ERP share the same products and buyers. Square sends payment, order, and customer webhooks in near real time; Business Central change subscriptions and a polling fallback on lastModifiedDateTime cover the reverse direction. Item and customer alignment runs on a schedule, typically every few minutes to hourly.

How ml-connector handles it

The connector holds two credential sets and bridges them per request: a Square Bearer token (refreshed before its 30-day expiry) and a Business Central OAuth2 client-credentials token scoped to https://api.businesscentral.dynamics.com/.default. Square webhooks are verified with HMAC-SHA256 over the signature key, notification URL, and raw body using a constant-time compare, returning 403 on failure; a bad signature is never accepted. Business Central change subscriptions are renewed before the three-day expiry by a cron job, and because those notifications carry no payload the connector refetches the named resource. A Square payment is matched to a Business Central customer by reference id or email, written as a draft sales invoice, then posted with Microsoft.NAV.post and settled through a customer payment journal line. Since Square has no chart of accounts, location id and item category map to Business Central GL dimensions so revenue posts to valid accounts. Writes are deduplicated with a Square idempotency_key on creates and a stable BullMQ jobId on the Business Central side; the Square invoice gotcha (an order must exist before an invoice) is respected when invoices are involved. On 429 from either side the connector backs off with jitter and retries.

A real-world example

A regional specialty coffee roaster with about 60 staff runs eight retail cafes and an online shop on Square while keeping its books in Microsoft Dynamics 365 Business Central. Every night a bookkeeper exports Square sales by location and re-keys totals into the ERP, which is slow and drifts out of balance when refunds land late. With the connector, each completed Square payment posts as a sales invoice and a settled payment journal line in Business Central, tagged to the cafe location as a GL dimension, so daily revenue by store is accurate without manual entry and refunds reconcile automatically.

What you can do

• •Post completed Square payments and orders into Microsoft Dynamics 365 Business Central as sales invoices with the bound post action.
• •Record Square settlements as customer payment journal lines applied to the matching Business Central invoice.
• •Map Square location ids and item categories to Business Central GL dimensions since Square has no chart of accounts.
• •Keep catalog items and customer profiles aligned in both directions between Square and Business Central.
• •Verify Square HMAC webhooks and renew Business Central change subscriptions so only changed records move.

Questions

How does the connector handle Square access tokens expiring every 30 days?

Square access tokens expire after 30 days, so the connector refreshes proactively using the non-expiring refresh token from the authorization code flow rather than waiting for a 401. The new token is stored encrypted and used as the Bearer credential on the next request. For a single Square account, a personal access token can be used instead of the OAuth flow.

Can Square map sales to the right GL accounts in Business Central?

Square is a commerce and payments platform and does not expose a chart of accounts or GL dimensions. The connector closes that gap by mapping Square location ids and item categories to Business Central GL dimensions, so each posted invoice lands on valid accounts. The Business Central accounts endpoint is read-only, so the mapping is configured in the connector, not written back to Square.

Why does the connector still poll Business Central if webhooks exist?

Business Central change subscriptions are push, but they carry no payload and expire after three days, so the connector renews them on a schedule and refetches each changed record. Some changes, such as edits by users who cannot run job queues, are not notified, so a polling fallback on the lastModifiedDateTime filter catches anything the subscription misses. Together they keep the two systems in step without missing updates.