Sage X3 and Paychex integration

What moves between them

The main flow runs from Paychex into Sage X3. When a payroll cycle completes, ml-connector receives Paychex payroll event notifications, fetches the full worker and payroll component data, and posts labor cost totals into Sage X3 GL accounts mapped to cost centers and departments. Worker hire, termination, and rehire events from Paychex flow into Sage X3 as headcount and job code records. Organizations and locations in Paychex are aligned with Sage X3 cost centers so that each payroll posting lands on a valid dimension. GL postings are read-only in Paychex, so ml-connector syncs payroll data into Sage X3 in one direction only: Paychex to X3.

How ml-connector handles it

ml-connector stores both credential sets encrypted: Paychex OAuth2 client credentials and Sage X3 HTTP Basic authentication or OAuth2 JWT bearer token. For Paychex, it acquires an access token using the Client Credentials grant and refreshes it proactively before expiry, since Paychex does not issue refresh tokens. For Sage X3, it handles the short 5-minute access token lifetime and maintains the 30-day refresh token to minimize authentication overhead. ml-connector receives Paychex webhook notifications and polls Paychex GET endpoints to fetch complete worker and payroll data, since webhook payloads contain only notification metadata. On the Sage X3 side, it uses GraphQL (Xtrem) or REST (api1) to post GL entries into the customer's X3 instance using the customer-specific server URL and folder name. Cost centers and departments are validated before payroll posting so every labor journal references a GL account that exists in X3. Because Paychex retries webhooks every 5 minutes on non-2XX responses, ml-connector returns 2XX for all webhook receipts and handles failures asynchronously in the background. Every record carries a full audit trail and can be replayed if a downstream GL posting fails.

A real-world example

A mid-sized manufacturing company runs Sage X3 on-premise for production, procurement, and finance across three plants, and uses Paychex Flex for payroll and HR. Before the integration, the accounting team ran a payroll register export from Paychex after each pay cycle, manually mapped labor costs to plant cost centers, and re-entered the totals into Sage X3. Month-end close was delayed while finance chased differences between HR headcount records and the labor cost totals in the GL. With Sage X3 and Paychex connected, each payroll cycle's labor costs flow automatically into X3 allocated to the correct plant cost center, and worker changes keep headcount aligned. The accounting team starts month-end close with the labor accounts already reconciled and the manual re-entry step eliminated.

What you can do

• •Receive Paychex payroll notifications and post labor cost totals into Sage X3 GL accounts on a schedule aligned to your payroll calendar.
• •Sync Paychex worker hires, terminations, and rehires into Sage X3 headcount and job code records.
• •Map Paychex organizations and locations to Sage X3 cost centers so payroll allocations land on valid GL dimensions.
• •Authenticate Paychex with OAuth2 client credentials and refresh tokens proactively, and Sage X3 with HTTP Basic or OAuth2 JWT bearer token.
• •Receive Paychex webhooks with full audit trail, handle retries and failed postings, and replay records if needed.

Questions

Which direction does data move between Sage X3 and Paychex?

The main flow is from Paychex into Sage X3. Payroll event notifications, worker records, and labor cost totals flow from Paychex into X3 as GL entries, cost center mappings, and headcount data. GL accounts and cost centers are validated in both directions so payroll lands on valid dimensions. Paychex has no finance or ERP capabilities, so no data flows back to Paychex from X3.

How does ml-connector handle Paychex webhooks and token refresh?

ml-connector receives Paychex webhook notifications for worker and payroll events, but since Paychex webhook payloads contain only metadata, it polls Paychex GET endpoints to fetch the full worker and payroll component data. For authentication, it acquires a Paychex OAuth2 access token using Client Credentials grant and refreshes it proactively before expiry, since Paychex does not issue refresh tokens. On every webhook, ml-connector returns 2XX immediately and processes the data asynchronously in the background.

How does ml-connector work with Sage X3's customer-specific server URL and lack of webhooks?

Every Sage X3 customer has a unique server URL, port, and folder name with no shared tenant registry. ml-connector accepts the full customer-specific X3 instance URL and uses it to route GL postings and headcount syncs. Because X3 has no native webhooks, ml-connector polls X3 for GL account and cost center master data on a defined schedule, aligns it with Paychex organizations and locations, and then posts payroll labor costs into the validated GL accounts after each payroll cycle.