Microsoft Dynamics 365 F&O and Square integration

What moves between them

The main flow runs from Square into Microsoft Dynamics 365 F&O. ml-connector reads Square payments, refunds, and payouts and posts them into D365 as customer payment journal lines and receivables, mapped to the matching main accounts and financial dimensions, with each Square location resolved to a legal entity. Paid invoices and completed orders post as customer sales so revenue is recognized in the ledger. Customer profiles flow the same direction so the D365 customer master reflects Square buyers, and catalog references are aligned so order lines resolve to real D365 products. Square has no GL resource, so ml-connector never writes ledger entries back into Square.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the Square side it sends the Bearer access token and the Square-Version header on every call, proactively refreshing the OAuth2 token before its 30-day expiry rather than waiting for a 401, and it scopes each read to the right location_id. On the D365 side it accepts the full tenant operations.dynamics.com host per customer, requests a Microsoft Entra ID client-credentials token, and re-requests it when the hour expires. Square locations and catalog items are mapped to D365 legal entities, financial dimensions, and product numbers first, so every posting lands on a valid account. Square HMAC-SHA256 webhooks for payment, refund, and payout events act as triggers, verified with a constant-time compare before processing and answered with a prompt 200 so Square does not retry, while the work runs asynchronously. Because D365 Business Events are stubs and order is not guaranteed, ml-connector polls OData for the full record on a schedule rather than trusting the push payload. Square writes carry an idempotency_key and D365 uses natural keys with no idempotency header, so ml-connector dedupes on the Square payment id and a BullMQ jobId before posting to D365, which avoids double-booking a re-read payment. D365 returns HTTP 429 with Retry-After and Square returns 429 with rate-limit headers, so both sides back off and retry. Every record carries a full audit trail and can be replayed if a downstream call fails.

A real-world example

A regional specialty retailer with a dozen storefronts and an online shop runs Microsoft Dynamics 365 F&O for finance and inventory and takes every sale through Square at the counter and online. Before the integration, a bookkeeper exported Square reports each morning and keyed daily takings, refunds, and the bank payout into D365 by hand, so the receivables never tied to the deposit and reconciling card fees against the ledger dragged into month-end close. With Microsoft Dynamics 365 F&O and Square connected, each payment, refund, and payout posts into D365 automatically, allocated to the legal entity and dimension for the location it came from. The deposits already reconcile, the manual export step is gone, and close starts from numbers that agree.

What you can do

• •Post Square payments, refunds, and payouts into Microsoft Dynamics 365 F&O as customer receivables against the correct main accounts.
• •Map each Square location to a D365 legal entity and financial dimension so takings land on valid accounts.
• •Keep the D365 customer master aligned with Square buyer profiles, and resolve order lines to real D365 products.
• •Authenticate Square with OAuth2 token refresh and D365 with Microsoft Entra ID client credentials.
• •Trigger on HMAC-verified Square webhooks, dedupe on payment id and jobId, and keep a full audit trail on every record.

Questions

Which direction does data move between Microsoft Dynamics 365 F&O and Square?

The main flow is Square into Microsoft Dynamics 365 F&O. Payments, refunds, payouts, paid invoices, and customer profiles move from Square into D365 as receivables and customer records, while catalog references are aligned so order lines resolve to real products. Square has no chart of accounts, so the general ledger stays in D365 and ml-connector never writes ledger entries back into Square.

Does Square push events, or does ml-connector poll Dynamics 365 F&O?

Both happen. Square pushes HMAC-SHA256 signed webhooks for payment, refund, and payout events, which ml-connector verifies and uses as triggers. D365 Business Events are lightweight stubs and delivery order is not guaranteed, so ml-connector polls the D365 OData API to read the full record and to post the journals, paging through results on a schedule you control.

How are duplicate payments prevented when records are re-read?

Square write operations accept an idempotency_key, but D365 OData has no idempotency header and relies on natural keys. ml-connector dedupes on the Square payment id together with a BullMQ jobId before it posts to D365, so a payment that is re-read after a webhook retry or a poll is not booked twice. Failed posts are retried with backoff against the 429 limits on both sides.