You can run a payroll successfully after completing the preliminary steps involved. You need to:

• create a company
• create and update the company's tax setups
• create the company's employees
• create and update the employees' tax setups

To run your company's payroll, you can call the following endpoints:

1. Start default payroll
2. Retrieve payroll status
3. Next payroll step
4. Previous payroll step
5. Discard payroll
6. Payroll overview

Start default payroll

📘

Errors and Warnings

When calling the payroll endpoints and you get error messages, they block the payroll from running. Error messages may be as a result of wrong configurations or information setup. In such cases, you can Discard Payroll or contact support.

Moreover, getting warning messages when calling the payroll endpoints will not block the payroll from running. The payroll will continue running as the warning messages are informative only.

When running your payroll, the start default payroll endpoint is the first one you call. When you call this endpoint, the payroll will run based on your already-defined payroll policy. Calling the endpoint returns a unique and essential ID, the RunId, with which you track and call other endpoints for the payroll.

Payroll run is generally presented as a wizard leading you through the process and calculation. The payroll wizard has five steps in the UI, which are:

• Inprogress- This is the default UI step if payroll run processing is somewhere between UI steps in the payroll run wizard.
• Timesheet- This is the next UI step after making the endpoint call.
• Overview - This is the next UI step that displays the information used for payroll processing.
• Locked- This UI step is where the payroll is finalized and payments are processed.
• Finished -This is the final UI step switched to directly from Locked after payment has been correctly processed and the payroll is finalized.

A successful call of the payroll endpoints returns the following properties:

For every particular internal processing state endpoint returns also description (currentProcStepDesc), progress (currentProcStepProgress), and status (currentProcStepStatus), which can be used to show progress in UI. With this differentiation, you can better view the calculation process.

Payroll processing runs as a background operation and will continue to the next UI step without a browser. You can run the next step and close the browser without issues.

Retrieve payroll status

Calling this endpoint returns data about the payroll run for UI rendering. You use the RunId returned when you call the Start payroll run endpoint to obtain information about the payroll.

After calling Start Payroll/Next Step/Previous Step, it is necessary periodically to call Retrieve Payroll Status. The payroll process runs in the background, so you must check the status/progress. You must call Retrieve payroll status until the currentUI differs from Undefined. Then, you know which UI step you are currently in.

Next payroll step

When you call this endpoint, you task the system to move the payroll forward. Moving to the next step of the payroll run will process all needed calculations and operations between the current and next steps. The payroll processing is done in the background and continues even if the front-end application fails. The system returns status data about the payroll run for UI rendering.

Payroll whose UI step is in Locked and has the payroll processing already finalized cannot be moved to the next step by calling this endpoint. It will be moved to the next step automatically by the system.

Previous payroll step

Calling this endpoint tasks the system to move the payroll backward. Moving the payroll to the previous step will process all needed rollbacks, discards, and operations between the current and following steps. The payroll processing is done in the background and continues even if the front-end application fails. The system returns status data about the payroll run for UI rendering.

Although, once the payroll has the UI step of Locked, it is impossible to move to the previous step.

Discard payroll

When you call this endpoint, you task the system to discard the running payroll. After discarding the payroll, the RunId will no longer be valid for other calls regarding the payroll.

Discarding payroll will process all needed rollbacks, removals, and operations. Payroll will be wholly removed along will all changes made in the timesheet. However, payrolls in the Locked UI step cannot be discarded after the deadline.

Payroll overview

This endpoint retrieves the payroll properties and reports. You can call this endpoint only on the finished payroll. Payrolls in progress will not return all data as they are available in non-finished stages.

Reports are generated in downloadable PDFs and can be served directly to you.

When you call this endpoint successfully, it returns the following list of properties: