Payroll Run

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

πŸ“˜

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:

PropertyDescriptionData Type
companyIdThe ID of the company during Create companyint32
runIdThe ID of the payroll runint32
payrollTypeThe payroll type member denoted by integers from 0-4 (Regular, Bonus, OffCycle, Void, and Termination, respectively).int32
startedOnPayroll start dateDate-Time
payDayPayroll paydayDate-Time
periodStartPayroll period start dateDate-Time
periodEndPayroll period end dateDate-Time
daysToProcessPaymentsDays to process paymentsint32
deadlineFinish payroll by this date and timeDate-Time
currentUIStepThe current UI step for the wizard denoted by integers from 0-4 (InProgress, Timesheet, Overview, Locked, and Finished, respectively).int32
currentProcStepThe current internal processing stateint32
currentProcStepDescCurrent step descriptionstring
currentProcStepProgressCurrent step progress in percentageint32
currentProcStepStatusCurrent step status members, denoted by integers from 0-5 (Invalid, NotStarted, Started, CancelRequested, Cancelled, and Finished, respectively).int32
directionDenoted by integers from 0-1 (Forward, Back respectively).int32

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.

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.

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.

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.

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.

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:

PropertyDescriptionData Type
totalEarningsTotal earnings paid to all employees in the payrollDouble
totalAmountThe total amount for the current payroll including all earnings, employer's taxes, SUTAs, and deductionsDouble
totalEETaxesThe total sum of all the taxes from pay statements in the payrollDouble
totalERTaxesThe total sum of all employer taxes from pay statements in the payrollDouble
totalDeductionsThe total sum of all deductions from pay statements in the payrollDouble
totalChecksAmountThe total sum of all check amounts in the payrollDouble
printedChecksCountCount of checks for printingint32
accountRequiredAmountThe amount required on the account to pay payrollDouble
daysToProcessPaymentDays to process paymentsint32
deadlineDeadline to finish payroll by this date and timeDate-Time
accountNumberAccount for paymentsString
employeesDetailed payroll overview for all employees in the payroll containing payStubId (Pay stub ID with int32 type), name (Employee name with string type), id (Employee's ID with int32 type), number (Employee's number with int32 type), hours (Hours paid in the current payroll with double type), grossPay (Gross pay amount in the current payroll with double type), inputedIncome (Inputed income in the current payroll with double type), reimbursements (Amount of reimbursements income in the current payroll with double type), total (Total amount in the current payroll with double type), taxes (Total taxes in the current payroll with double type), deductions (Total deductions in the current payroll with double type), and netPay (Current payroll net pay with double type).Array of objects
employeesTaxesAll taxes for employees in pay statements containing text (Tax description with string type), and amount (Tax amount with double type).Array of objects
employersTaxesAll employer taxes from pay statements in payroll containing text (Tax description with string type), and amount (Tax amount with double type).Array of objects
deductionsAll deductions from pay statements in the payroll containing id (Deduction ID with int32 type), description (Deduction description with string type), type (Deduction type with int32 type), deduction (Employee deduction amount with double type), contribution (Employer deduction contribution with double type), and total(Total deduction amount with double type).
reportsAll reports created as part of the payroll run containing caption (Report name with string type), description (Reprt Report description with string type), fileId (Report ID needed to download report through File download endpoint with int64 type), fcu (Report file token required to download report via File download endpoint with string type), fileUrl (Direct file URL with string type), and fileToken (Report file token with string type).Array of objects