Microsoft Dynamics 365 F&O and GoCardless integration

What moves between them

The main flow runs from GoCardless into Microsoft Dynamics 365 F&O. As payments confirm and payouts settle, ml-connector reads the collected payments, refunds, fees, and chargebacks and posts them into F&O as customer payment journal lines and ledger entries, mapped to the matching F&O customer accounts and financial dimensions. Payout items are read to break each payout into its underlying payments and fees so the bank deposit reconciles against the receivables it covers. Customer records can flow from F&O into GoCardless so a mandate and payment can be set up for an existing F&O customer. GoCardless owns no general ledger, so ml-connector never writes ledger entries back into GoCardless.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the GoCardless side it sends the Bearer access token and the GoCardless-Version header on every request and switches between the live and sandbox hosts by the environment field. On the F&O side it requests an Entra ID client credentials token scoped to the tenant environment host, refreshes it before the roughly one-hour expiry, and accepts the full operations.dynamics.com URL per customer since there is no shared base address. GoCardless webhooks arrive signed with HMAC-SHA256 in the Webhook-Signature header, so each batch is verified against the endpoint secret before processing and a mismatch returns 401 rather than 200, which keeps GoCardless retrying. Because a webhook payload references a resource rather than carrying full detail, the handler reads back the payment or payout from the GoCardless API, then resolves the customer and posts the journal line in F&O. Customer accounts and financial dimensions are mapped first so every line lands on a valid dimension string in the format F&O expects. GoCardless amounts are integers in the smallest currency unit, so ml-connector converts pence and cents to the decimal amount F&O stores. F&O entity keys must be fully specified including dataAreaId, so writes are scoped to the right legal entity. Both sides return HTTP 429 under load, so ml-connector honors the GoCardless rate-limit headers and the F&O Retry-After header and backs off. GoCardless can deliver a webhook more than once, so the event id and a BullMQ jobId dedupe it, and a scheduled poll of the GoCardless event log backfills anything a webhook missed. Every record carries a full audit trail and can be replayed if an F&O post fails.

A real-world example

A mid-sized subscription services company with a few thousand customers bills monthly and runs Microsoft Dynamics 365 F&O for accounts receivable and the general ledger, while collecting payments by direct debit through GoCardless. Before the integration, the finance team exported a GoCardless payout report each time money landed in the bank and keyed the totals into F&O, then spent the first days of month-end close matching the single bank deposit against the dozens of customer invoices it covered and chasing failed collections and chargebacks by hand. With Microsoft Dynamics 365 F&O and GoCardless connected, each confirmed payment posts against the right customer as it settles, every payout is split into its underlying payments and fees through payout items, and refunds and chargebacks post automatically. The deposits already reconcile, failed collections are visible in the ledger, and the manual export-and-key step is gone.

What you can do

• •Post confirmed GoCardless payments into Microsoft Dynamics 365 F&O as customer payment journal lines against the right customer accounts.
• •Reconcile each GoCardless payout to its underlying payments, fees, refunds, and chargebacks using payout items so bank deposits tie out in the F&O ledger.
• •Set up GoCardless mandates and payments for existing F&O customers so collections start from the customer master.
• •Authenticate GoCardless with its Bearer access token and version header, and F&O with Microsoft Entra ID OAuth2 client credentials.
• •Verify GoCardless webhooks by HMAC-SHA256, dedupe by event id and jobId, and keep a full audit trail with replay on every record.

Questions

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

The main flow is GoCardless into F&O. Confirmed payments, refunds, fees, payouts, and chargebacks move from GoCardless into the F&O general ledger and customer payment journals. Customer records can move the other way so a mandate can be set up for an existing F&O customer. GoCardless has no general ledger, so ml-connector never writes ledger entries back into it.

How are GoCardless payouts reconciled against the F&O ledger?

A GoCardless payout bundles many payments, fees, refunds, and chargebacks into one bank deposit. ml-connector reads the payout items for each payout to enumerate every underlying transaction, then posts them into F&O split across the correct customer accounts and financial dimensions. That way the single deposit in the bank reconciles against the individual receivables it covers.

Does GoCardless push events, or does ml-connector poll for them?

GoCardless webhooks are the primary path, so ml-connector verifies each batch by HMAC-SHA256 and acts on payment confirmed, paid out, failed, and charged back events as they happen. Because a webhook references a resource rather than carrying full detail, the handler reads the payment or payout back from the API before posting. A scheduled poll of the GoCardless event log backfills anything a webhook missed, and F&O itself is polled on a schedule since its Business Events are not real-time.