Sage X3 and PayPal integration

What moves between them

The main flow runs from PayPal into Sage X3. When a customer payment is captured and settled in PayPal, ml-connector receives the webhook notification, looks up the matching Sage X3 customer and GL account, and records a sales receipt or invoice payment in Sage X3's accounts receivable ledger and general ledger. PayPal settlement transactions flow into Sage X3's cash receipts so bank reconciliation matches. Refunds and chargebacks flow back to reverse the sales transaction. Reference data such as customer IDs are aligned so PayPal order metadata carries the matching Sage X3 customer number.

How ml-connector handles it

ml-connector stores PayPal client credentials encrypted and requests an OAuth2 bearer token at the start of each sync run, caching it until expiry approaches. On the Sage X3 side it accepts either the legacy HTTP Basic auth path (api1 with explicit enable required in nodelocal.js) or the modern OAuth2 + GraphQL path (Xtrem, V12+), determined at configuration. PayPal pushes payment and order events to a registered webhook endpoint, and ml-connector verifies the RSA-SHA256 signature on every event before processing. For each transaction, ml-connector queries Sage X3 to validate the target customer ID and GL account exist, then posts the payment or refund to the correct accounts receivable and GL entry records. Sage X3 access tokens expire in 5 minutes, so ml-connector refreshes them before each call. Payment amounts and dates are validated against PayPal's source to detect tampering. Every record is audited with the original PayPal transaction ID and timestamp.

A real-world example

A mid-sized e-commerce and wholesale distributor runs Sage X3 in the cloud for finance and inventory, and uses PayPal to accept customer payments online and via invoice links. Before the integration, the accounting team exported PayPal transaction reports weekly and manually entered each payment into Sage X3's cash receipts, mapping customer PO numbers to the correct Sage X3 customers. Refunds and chargebacks required manual reversal of the original receipt entry. With Sage X3 and PayPal connected, each customer payment appears in Sage X3's accounts receivable within seconds of PayPal settlement, pre-mapped to the customer and GL account, and refunds automatically reverse the original entry. Month-end AR reconciliation matches the Sage X3 GL to the PayPal settlement report without discrepancy, and the team's manual re-entry work is eliminated.

What you can do

• •Record PayPal customer payments and captures into Sage X3 accounts receivable and general ledger, mapped to the correct customer and GL account.
• •Automatically post PayPal refunds and chargebacks as reversals to the original Sage X3 sales transaction.
• •Reconcile PayPal settlement transactions to Sage X3 bank deposits and cash receipt records.
• •Validate PayPal customer metadata against Sage X3 customer IDs and GL accounts before posting to prevent posting to invalid dimensions.
• •Support both legacy HTTP Basic auth (REST api1) and modern OAuth2 (GraphQL Xtrem) Sage X3 connectivity depending on version and customer setup.

Questions

Does this integration work with both on-premise and cloud Sage X3 deployments?

Yes, it works with both. On-premise deployments use HTTP Basic auth via the legacy REST api1 endpoint, which requires explicit enablement by the customer admin in nodelocal.js. Cloud deployments can use either the legacy REST path or the modern OAuth2 + GraphQL (Xtrem) path depending on Sage X3 version (V12+). ml-connector detects the configured auth method at setup.

How are PayPal transactions matched to Sage X3 customers and GL accounts?

PayPal order records and payment metadata carry a reference field (such as invoice_id or custom_id) that stores the Sage X3 customer ID. When a payment is received, ml-connector looks up that Sage X3 customer ID, retrieves the default AR and revenue GL accounts configured for that customer, and posts the payment to those accounts. If the customer ID is invalid or missing, the transaction is flagged for manual review.

What happens if a PayPal refund or chargeback occurs after the original payment is posted to Sage X3?

ml-connector receives the PayPal refund or dispute event via webhook, queries Sage X3 for the original sales transaction using the PayPal transaction ID stored in the audit trail, and posts an offsetting reversal entry to zero out the original receipt and GL posting. The reversal entry is linked to the refund transaction ID for full traceability.