Sage X3 and GoCardless integration

What moves between them

The main flow is from GoCardless into Sage X3. As customers pay via direct debit, GoCardless publishes payment, refund, and payout events to ml-connector's webhook endpoint. ml-connector verifies each webhook batch with HMAC-SHA256, extracts the payment detail, and posts the receipt as a GL entry into Sage X3's accounts receivable clearing account, offset against the revenue account for the product or service. Refunds and failed payments are tracked so the AR aging report stays accurate. GoCardless payouts are read-only in GoCardless, so ml-connector does not write back.

How ml-connector handles it

ml-connector stores the GoCardless bearer token and registers a webhook endpoint with GoCardless, then listens for payment, refund, and payout events. Each webhook batch arrives signed with HMAC-SHA256 using the webhook secret; ml-connector computes the signature on the raw request body and rejects any batch where the signatures do not match, returning 401 to GoCardless so it retries. For Sage X3, ml-connector accepts the customer's unique X3 hostname and port, plus the target folder and GL account numbers for AR clearing and revenue. When a payment event arrives, ml-connector posts the receipt amount as a GL entry into Sage X3 using either OAuth2 bearer token (GraphQL) or HTTP Basic auth (REST api1), depending on the customer's X3 version. Each payment is tagged with the GoCardless payment ID for deduplication, so a retried webhook does not double-post into the ledger. Refunds are posted as reversals to the same GL entry. Currency amounts are converted from GoCardless pence/cents to Sage X3's base currency decimal. Every payment carries a full audit trail and can be replayed if a downstream GL post fails.

A real-world example

A UK-based subscription software company runs Sage X3 cloud for finance and subscription billing, and uses GoCardless to collect recurring payments from its customer base across the EU and UK. Before the integration, the billing team exported GoCardless payment reports at month-end and manually entered each receipt and refund into Sage X3's AR register, a process that took a full day and was error-prone when partial refunds or failed collections arrived mid-month. With Sage X3 and GoCardless connected, every payment and refund posts automatically the moment it clears the bank, the AR aging report runs from live data, and month-end close no longer requires manual reconciliation of the payment ledger.

What you can do

• •Post GoCardless payment receipts and refunds as GL entries into Sage X3's accounts receivable and revenue accounts in real time.
• •Verify GoCardless webhook signatures with HMAC-SHA256 and reject unsigned or tampered event batches to prevent fraudulent GL entries.
• •Deduplicate payments across webhook retries using GoCardless payment IDs so the same receipt does not post twice.
• •Authenticate GoCardless with bearer tokens and Sage X3 with OAuth2 (GraphQL) or HTTP Basic auth (REST api1) depending on the customer's deployment.
• •Keep a full audit trail of every payment, refund, and failed collection with timestamps and amounts in both systems so month-end AR reconciliation is traceable.

Questions

How does ml-connector verify GoCardless webhook authenticity?

GoCardless signs each webhook batch with HMAC-SHA256 using the webhook secret. ml-connector computes the signature on the raw request body and compares it to the Webhook-Signature header. If the signatures do not match, ml-connector returns 401 to GoCardless so the batch is retried, preventing fraudulent GL entries from posting into Sage X3.

How are GoCardless payments matched to Sage X3 customers and accounts?

ml-connector maps each GoCardless customer to a Sage X3 customer number and tags payments with the configured AR clearing GL account and revenue account. The mapping is stored encrypted in ml-connector and applied on each payment. Currency amounts are converted from GoCardless pence or cents to Sage X3's base currency decimal.

What happens if a webhook is retried or a GL post fails?

Each payment is tagged with the GoCardless payment ID; a retried webhook does not post the same payment twice. If the GL post to Sage X3 fails, the payment is queued for replay with full tracing in the audit log, so no receipts are lost and month-end reconciliation can be verified.