Payroll integration
Oracle HCM to Paychex Flex integration: US hires from Oracle HCM Cloud as in-progress workers in Paychex Flex
An integration between Oracle HCM Cloud and Paychex Flex prepares a hire at a US legal employer in Oracle as an in-progress worker in the right Paychex company, with name, person number and personal email. Paychex then invites the new employee to fill in tax forms and bank account in Flex themselves, after which the worker becomes active.
What the integration does
Organisations that use Oracle HCM Cloud worldwide for HR and have US payroll processed by Paychex enter new US employees in Paychex Flex by hand. Anyone entered late only gets the invitation for W-4 and bank details after their first working day.
- HR saves a hire at a US legal employer in Oracle, often weeks before the start date.
- KoppelHet reads the newhire feed, fetches name and email addresses and determines the Paychex company for the legal employer.
- KoppelHet creates an in-progress worker with the personal email address as communication.
- Paychex sends the invitation; the employee fills in tax and bank account, the Flex administrator completes the rest.
- If the hire is cancelled in Oracle, KoppelHet reports the worker to the Flex administrator.
What to watch for with Oracle HCM Cloud and Paychex Flex
- Paychex invites an in-progress worker through the first channel it finds, in the order business email, personal email, business mobile. In Oracle email addresses are a list with a type per entry, and a starter often has no work address yet. KoppelHet therefore only sends the address of the personal type, so the invitation reaches the starter.
- Oracle already sends the newhire event for a future-dated hire. KoppelHet then creates the worker straight away, so the employee can fill in the W-4 and bank account in Flex before their first day and the first payroll does not wait.
- The Oracle feeds also report contingent workers and pending workers. The Paychex API only knows EMPLOYEE and INDEPENDENT_CONTRACTOR as worker types. KoppelHet only sends employees; a contingent worker as a 1099 contractor can be added later as an extension.
- A cancelled work relationship, for example after a no-show, has its own feed in Oracle. KoppelHet then deletes no worker in Paychex, but passes the in-progress worker with the reason from Oracle to the Flex administrator.
- Each US legal employer in Oracle is a separate company in Paychex with its own companyId, and each company approves the integration separately. A Flex Admin does this under Company Settings, Integrated Applications, after a request with that company's eight-digit displayId.
- If a company's Paychex account is locked, the API returns a 423 and may still return a workerId. Paychex calls that ID invalid. KoppelHet does not store it with the Oracle person and retries the hire once the account is open again.
- With several hires in one request, each worker needs a workerCorrelationId. KoppelHet fills in the Oracle PersonNumber there, so each workerId in the response lands with the right person in Oracle.
How we build and run it
- The integration runs on the KoppelHet platform, hosted in a data centre in the EU.
- Every sync and every error is visible in the functional log; on an error your administrator is notified.
- A change that cannot go through is not half-applied but queued for another attempt.
- KoppelHet is ISO 27001 certified. Data travels encrypted and stays on the platform no longer than needed.
- After go-live we manage the integration and adjust it when your process changes.
- The integration fits next to your existing integration layer. Only the fields in the design are transferred; the platform keeps no register of its own.
Implementation and price
This is not an app you switch on. We build the integration for your organisation on our platform, with building blocks we reuse on every project. So it is custom work that does not start from scratch.
A consultant prepares the intake and analyses both systems. We then record the mapping and exceptions field by field, test in the test or acceptance environment and go live at a moment you choose. Costs are a one-off amount for the setup and a monthly amount for platform, monitoring and support.
Frequently asked questions
Do pay changes from Oracle also go to Paychex?
Not in the first version. Paychex has a compensation endpoint on the worker, so it can be added later as an extension after a test with the customer.
Why does the integration not fill in the W-4?
The employee makes those choices themselves, and they are usually not in Oracle when US payroll is external. Through the Paychex invitation the employee fills them in within Flex.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- Oracle HCM Cloud through the employee Atom feeds newhire and cancelworkrelship on /hcmRestApi/atomservlet/employee/, then the REST resource workers for names, emails and workRelationships, filtered on US legal employers and worker type employee.
- Paychex through api.paychex.com with KoppelHet's partner app. Client access through POST /management/requestclientaccess with the displayId and approval in Flex (optional CLT_ACCESS webhook). Create with POST /companies/{companyId}/workers; communication, compensation, tax and direct deposit can follow on the workerId.
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in Oracle HCM Cloud | Field in Paychex Flex | Notes |
|---|---|---|
PersonNumber | workerCorrelationId | Links the response to the right person |
names (FirstName) | givenName | Required |
names (LastName) | familyName | Required |
Worker type employee | workerType EMPLOYEE | Required |
emails (privé) | communications EMAIL met usage PERSONAL | |
Legal employer | companyId | Lookup table |
Related
Ashby → Oracle HCM Cloud
Ashby to Oracle HCM integration: an accepted offer on an opening becomes a pending worker
Bullhorn → Oracle HCM Cloud
Bullhorn to Oracle HCM integration: an approved placement of an employee becomes a pending worker
Carerix → Oracle HCM Cloud
Carerix to Oracle HCM integration: successful placement as a pending worker in Oracle HCM Cloud
Greenhouse → Oracle HCM Cloud
Greenhouse to Oracle HCM integration: accepted offer as a pending worker in Oracle HCM Cloud