Payroll integration
Lucca to ADP iHCM integration: fixed and variable pay from Lucca Compensation to Dutch ADP payroll
An integration between Lucca and ADP iHCM passes base salary and variable pay from Lucca Compensation, plus the end date of the employment, to Dutch payroll in ADP iHCM. For employees of the Dutch legal entity who already exist in ADP, payroll then retypes nothing; creating a new employee in ADP remains work for payroll.
What the integration does
Organisations that use Lucca for HR and pay management and have Dutch salaries at ADP iHCM send payroll an overview of pay rises and variable pay from Lucca every month. A variable item deleted in Lucca after sending then stays in ADP until someone notices.
- HR records a new fixed or variable pay item in Lucca, or sets an end date on an employment.
- Lucca reports the change; KoppelHet fetches the item and the employment and checks the legal entity.
- The base salary goes to ADP as a salary change, a variable amount as a line in the item's pay period.
- An end date on the employment starts the termination in ADP.
- Anything ADP rejects is in the overview for payroll with the error message.
What to watch for with Lucca and ADP iHCM
- Lucca automatically closes an open fixed pay item on the day before a new item of the same kind starts. KoppelHet therefore only reads the new item and sends its start date to ADP as the effective date; a separate end date for the old salary is not needed in ADP.
- A variable pay item in Lucca belongs to one period and can be an amount or a quantity, depending on the nature. KoppelHet only sends natures of type amount to ADP; a quantity, such as hours, goes to payroll as a notification in the first version.
- Lucca marks a deleted variable item as deleted instead of letting it disappear. If the amount has already gone to ADP, KoppelHet sends the same amount with a minus as a correction, as ADP prescribes for variable data already submitted.
- Lucca delivers webhook notifications at least once, but not always in order. ADP processes only one salary change per call. KoppelHet first sorts the notifications by the time of the change in Lucca and then sends them one by one, so an old pay rise does not overwrite a new one.
- An employment in Lucca belongs to one legal entity, and two employments of the same employee may not overlap. KoppelHet translates the Dutch entity to the ADP pay group and leaves employments at other entities out of the integration.
- A change to an employment in Lucca is retroactive. If HR moves the end date while the termination is already in ADP, KoppelHet cancels it and starts it again with the new date, because ADP does not allow an end date to be edited.
- In Lucca, webhooks only work once event saving is enabled or an active webhook endpoint exists. KoppelHet sets up that endpoint at the start, and also runs a daily check, so a missed notification is caught before the ADP submission.
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 we need Lucca Compensation?
Yes, for salary and variable pay. Without that module only departures can go from Lucca to ADP.
Does the integration create new employees in ADP?
No. We found no public ADP API to create someone in iHCM NL. Payroll does that; KoppelHet then links the employee.
What about Lucca users in France or Switzerland?
They stay outside the integration. Only employments at the Dutch legal entity go to ADP.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- Lucca Compensation API (legacy) with the header Authorization lucca application={api_key}: /remuneration/api/fixed-items (amount, natureId, workContractId, amendmentId, periodStart; a new open item closes the previous one the day before) and /remuneration/api/variable-items (amount, natureId, period, isDeleted; nature type Amount or Number). Lucca API (2024-11-01) for employments with filter legalEntity.id, webhook endpoints and events with occurredAt.
- ADP iHCM through GET /hr/v2/workers, the Base Remuneration Change API (2416 and 2417, one event per call), the Pay Data Input API for iHCM NL (corrections as negative values) and the Worker Terminate API (worker.terminate, worker-termination.cancel). Canonicals in the Consumer Application Registry (CAR).
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in Lucca | Field in ADP iHCM | Notes |
|---|---|---|
employee.id | payrollfilenumber | Linked once and stored by KoppelHet |
employment.legalEntity | payrollGroupCode | Lookup per legal entity |
Fixed item amount (natuur basissalaris) | Salarisbedrag 2417 met salariscode 2416 | |
Fixed item periodStart | effectiveDateTime van de salariswijziging | |
Variable item amount, natureId en period | Variabel veld (Vxxx) met de begin- en einddatum van de periode | Lookup per nature |
Employment end.date | Beëindiging in worker.terminate |
Related
Lucca → Active Directory
Lucca to Active Directory integration: accounts in your own domain based on Lucca
Lucca → AFAS Profit
Lucca to AFAS integration: employees and pay of the Dutch entity from Lucca in AFAS
ASLucca → Arbodienst (SIVI)
Lucca to the occupational health service via SIVI: confirmed sickness per half day as absence reports
Lucca → DATEV
Lucca to DATEV integration: German joiners, leavers and master data from Lucca to DATEV