Sage X3 and Stripe integration

What moves between them

The flow is primarily Sage X3 to Stripe. ml-connector polls Sage X3 for new or updated customers and sales invoices on a schedule you control. Each Sage X3 customer maps to a Stripe customer record with billing contact details and invoice-to-date totals. Each Sage X3 sales invoice becomes a Stripe invoice with the same invoice number, customer mapping, and line items, enabling Stripe to collect payment online. Stripe payment events and charge records flow back into Stripe's audit log, and ml-connector logs the payment status against the corresponding X3 invoice record for reconciliation. Refunds and disputed charges are tracked in the audit trail but do not flow back into X3 GL entries, as Sage X3 and Stripe operate at different accounting layers.

How ml-connector handles it

ml-connector stores the Sage X3 OAuth2 client credentials encrypted and refreshes the JWT bearer token every 4 minutes to stay ahead of the 5-minute expiry. It accepts the customer-specific Sage X3 server URL and folder name, validates that the X3 instance is reachable, and uses the updatedDate field to poll only records changed since the last run, reducing API load. On the Stripe side, ml-connector uses the API secret key to create or update Stripe customers with contact and company details from X3, mapping the X3 customer number to a stable Stripe customer ID. Sales invoices from X3 are posted to Stripe with the same invoice number, customer reference, line items, and totals, and ml-connector tracks the Stripe invoice ID in the audit log for future lookups. Stripe's HMAC-SHA256 webhook signatures are validated on each incoming event to ensure authenticity. Because Stripe charges are immutable and Sage X3 GL posting is independent, ml-connector never writes payment data or GL entries back to X3 - it logs the payment status for reconciliation and stores the full audit trail so disputes and refunds can be manually reviewed.

A real-world example

A mid-market distributor uses Sage X3 to manage inventory, procurement, and accounts receivable across three regional offices. Sales invoices are generated daily in X3 but customers still receive paper invoices or email attachments, leading to slow payment cycles and manual follow-up. With Sage X3 and Stripe connected, each invoice is automatically posted to Stripe moments after creation, and the distributor can email customers a secure payment link. Stripe collects the payment online, records the transaction, and the payment status flows back into the audit log for the finance team to reconcile against X3 accounts receivable at month-end close, eliminating the manual invoice distribution step and accelerating cash collection.

What you can do

• •Sync Sage X3 customers to Stripe with billing contact details and invoice-to-date balances.
• •Post Sage X3 sales invoices to Stripe with invoice number, customer mapping, line items, and totals for online collection.
• •Authenticate with Sage X3 using OAuth2 JWT bearer tokens and automatically refresh before expiry.
• •Validate Stripe webhook signatures and log payment events against X3 invoices for reconciliation.
• •Poll Sage X3 on a schedule you define using delta detection to minimize API load and latency.

Questions

Does the Sage X3 and Stripe integration write payment data back into Sage X3?

No. ml-connector posts Stripe customer and invoice data from Sage X3 into Stripe for payment collection, and it logs Stripe payment events and charge records in the audit trail for reconciliation. However, it does not write GL entries, payment allocations, or refund transactions back into Sage X3. Payment status is recorded in the audit log so your finance team can review and post journal entries manually at month-end.

How does ml-connector handle Sage X3's customer-specific server URL and 5-minute token expiry?

ml-connector accepts the full server URL and folder name for each Sage X3 instance, since X3 publishes no shared base address. It stores the OAuth2 client credentials encrypted and refreshes the JWT bearer token every 4 minutes, staying ahead of the 5-minute expiry to avoid authentication failures. Refresh tokens are valid for 30 days, and ml-connector logs token refresh events in the audit trail.

What happens to Stripe refunds and disputed charges?

Stripe refund and dispute events are delivered via webhook with full details including the original charge ID and reason. ml-connector logs these events in the audit trail and flags them so your finance team can review. Because Stripe operates at the payment layer and Sage X3 operates at the accounting layer, refunds do not automatically reverse GL entries in X3 - your team posts manual credit memos and adjustments based on the Stripe dispute log.