Payroll

The payroll run is a process in 6 steps, ensuring that salaries are paid, tax filings are made, pensions are paid, etc.

Payroll Types

• Monthly salary (paid in arrears) is used for employees who receive a monthly salary paid in arrears. This is selected on the employee's salary profile.
• Monthly salary (paid in advance) is used for employees who receive a monthly salary paid in advance.
• Biweekly pay is used for employees who are paid every 14 days.
• B-income is used when a B-fee is required. B-income is used, for example, by consultants on projects and freelancers who give concerts or presentations. In the case of B-income, no A-tax and AM contribution to eIncome / Tax will be reported or settled.
• Zero-filing is used to make a manual report to eIndkomst (Skat) in months where no salary has been reported.

Here are the payroll types enumeration used in our system.

Payroll Status

We use our payroll statuses as states for the payroll run, and in each state, the appropriate state endpoints can be used.
Here is an overview of the payroll statuses.

Payroll Stages

A company can have only one active payroll per payroll type. An active payroll is considered to be active until it is finished, reverted, or deleted.

If the user decides to delete the payroll, it will no longer exist, and the user can create a new payroll. This action is only allowed while the payroll is in draft stage.

To see which payroll type you can run runnable payroll types

To check payroll status by type of the payroll active payroll

Payroll run

Create payroll run

To create a new payroll, use the endpoint for create payroll

This endpoint will return payroll Uid for the created payroll, which will be the required argument in the following endpoints and actions. It will set the status of the payroll to DraftPreview.

It is important in the request to fill all the required fields

Example:

    {
  "type": 3,
  "dispositionDate": "2019-08-24T14:15:22Z",
  "periodFrom": "2019-08-24T14:15:22Z",
  "periodTo": "2019-08-24T14:15:22Z",
  "selectedEmployeeUid": [
    "00000000-0000-0000-0000-000000000000"
  ]
}

type - payroll types

dispositionDate - is the date when the payments for the payroll will be executed

selectedEmployeeUid - Uid of the employees who will be in the payroll run

note - there must be at least one employee in the request

Advanced (optional) options:

• Absence registration period (Period from - Period to)
• Mileage registration period (Period from - Period to)
• Hour registration period (Period from - Period to)
• Period for supplements and deductions (Period from - Period to)
• Note to all employees
• Extra payroll run (Toggle switch)
• Pay out special holiday allowance (Toggle switch)
• Transfer SH to holiday pay (Toggle switch)
• Pay out the SH balance (Toggle switch)
• Pay out free choice (Toggle switch)
• Pay out savings (Toggle switch)
• Pay out time in lieu (Toggle switch)
• Do not notify the employee/s about payslip/s (for this payroll run) (Toggle switch)

Employees

Employees can be pulled as list from the payroll API here

To add employees to the payroll, you must provide an array of employee ids in the selectedEmployeeUid attribute.

To change the settings of the payroll, use the endpoint for update here

To delete the payroll, use the endpoint for delete here

Draft Calculations

You can pull information about the payroll after it has been created here

It will return the settings for the payroll and basic information about all of the employees in the payroll including their Uid's which are required attributes for the following actions for a specific employee payroll.

result.employees[x].uid - Employee payroll Guid

If you want to view all the salary elements and calculations for specific employees inside the payroll, use this endpoint here

To perform Draft calculations for specific employees for the payroll here

This endpoint calculates the employee payroll if the calculations have not been done yet and provides the draft calculations for review before processing.

Once the draft calculation for the employee payroll is finished, the user can manage the following:

• View the payslip
• Salary and tax details
• Registrations
• AM pension
• Corrections
• Errors
• Log records

To update employee payroll, use the endpoint for update here .

Use this to edit all the salary data elements for the specific employee of the current payroll run.

To delete or remove an employee from the current payroll, use the endpoint for delete here

Control

Once everything settled, the user can continue to the control stage where the draft calculations and validations for all employes are being processed.

To trigger the control stage, use the endpoint for control

note - triggering this stage requires the payroll to be in the draft stage.

Once this endpoint is hit, the payroll status will be set to ControlProcessing. The processing of the calculations and validations for all the employees in the payroll could take a while, and when everything is finished, the status will be changed to ControlFinished.

Use the endpoint for payroll status to check the payroll status

Once the status is ControlFinished you can see the validations here

If there is an error in the validations, the payroll can not proceed further, and additional actions are required to fix the errors. You will need to go back to the draft and fix the error.

Generating reports here

in the body of the request, we send only “payrollReportType”, which is for the category of the reports:

• 1 – payslips
• 4 – accounting
• 7 – deviations
• 2 – payroll report
• 5 – tax report
• 8 – payments

After receiving status 204, the generation of the report is started, and it will take some time until they are ready for download

Downloading reports here

For payslips, only zip format is supported.
All other reports are only in CSV except the deviation report, which can be in PDF or CSV also.

Example
Payslips

GET /api/companies/{companyUid}/payroll/{payrollUid}/control/report?reportType=1&format=3

If there is a need to chage something in the payroll, some calculation is missing or there is error in the validations, you can go back to the draft status and edit the employee payroll data.
To do that, use the endpoint to change the status of the payroll here and set the status to 1

Review and Run

The next phase is the payroll review

This will return detailed information regarding the payroll run.

And the last step is actually running the payroll. To initiate that step, use the endpoint for payroll run here

note - to run the payroll, it is required that the payroll is in ControlFinished state and in the request, a valid verificationCode is provided*

To request a mobile Verification Code, use the endpoint

https://{{env_url}}/api/verification

where the env_url will be the API URL of the environment here

This call will trigger the job of sending the SMS code to the logged-in user, who should receive an SMS on their phone when finished. The code send in the message is your verificationCode for the payroll run.

After successfully triggering the endpoint for the payroll run, the final stage of the payroll run will start. The status will be set to Processing
and in this stage, the payroll will start creating payments and accountings, updating reports, payslips, and statistics and sending them to SKAT.

When everything is finished it will set the payroll status to finished. If the payroll fails, it will be returned to DraftReview.

B-income and Null Payroll

B-income

To create a B-income type
Use the endpoint for Payroll create with the appropriate body in the request.

Example

{"type":4,
"periodFrom":"2023-05-01T00:00:00.000Z",
"periodTo":"2023-05-31T00:00:00.000Z",
"dispositionDate":"2023-05-10T00:00:00.000Z",
"selectedEmployeeUid":["5865d0fd-c73f-48bc-a42c-6461daac243b"],
"isPaid":false,
"customRegistrationPeriods":[]}

note - this type of payroll is intended only for the b-income type of employee

Then, use the endpoint to get the data for the created payroll and employee payroll

Add payments to the payroll here

Example

{
  "rateUid": null,
  "name": "payment",
  "payCheckFor": "10",
  "unit": 1,
  "paymentPerUnit": 1233,
  "includeInPensionBase": false,
  "includeInAmPensionBase": false,
  "isIncludedInHolidayEntitlementSalary": false,
  "percentage": 0,
  "isIncludedInHolidayEntitlementSalaryReduction": false
}

Available paycheck for types that can be used for payments are:

• 10 -B-Income with contributions
• 11 - B-Income without contributions
• 13 - Reimbursement of Expenses

Or delete payment here

After that, use the endpoint for control, and the flow continues as regular payroll.

Null Payroll

To create a Null payroll
Use the endpoint for Payroll create with the appropriate body in the request.

Example

customRegistrationPeriods: []
periodFrom: "2023-05-01T00:00:00.000Z"
periodTo: "2023-05-31T00:00:00.000Z"
selectedEmployeeUid: []
type: 2

The type of the payroll is 2, which means null payroll, and PeriodFrom and PeriodTo - date range for the payroll

note - This type of payroll doesn't have any employees.

After it is created, use the endpoint to run the payroll with the valid verification code.