Creating Hourly Payments in BrightPay

The end point Create Employee Hourly Payments can accept a message per Employee to create hourly payment data. This means a request will pass or fail per Employee, so it is possible for data uploaded for some Employees to pass and for other Employees to fail.

Hourly Payments can only be loaded into the Employee’s current open payslip. Most of the time in BrightPay (for a particular Employer) all Employee's payslips for a particular date will all be in the same state. This means it is likely all Employees use the same pay periods (all paid monthly or every 2 weeks etc.). Also, for a particular date it is likely that all Employee’s payslips will be either finalised (closed), open or in the future.

Occasionally an individual's payslip may differ from the others. For example, if there has been an issue with a previous payslip and the previous payslip has been reopened. As it has been reopened the previous payslip will be considered that individual Employee’s current payslip by BrightPay. This will need fixed before the upload will work for that individual Employee (but the upload will work for the other Employees).

Occasionally different groups of Employees can be on different payment cycles or dates. For example, a company has bought over another company, has inherited Employees but has not align payslip cycles yet between the original and new Employees.

Once the Employees and the Hourly Rates have been mapped the next stage is to allow the user to select the dates of the Timesheets that the user wants to upload. The integration may also allow a user to specify if all Employees mapped or a subset should be uploaded.

EmployeeHourlyPaymentsRequestDTO Message

Once the

• Employees are mapped

• HourlyRates are mapped

• Potentially a subset of Employees are selected

• Relevant TimeSheets are selected

Then data can be moved to BrightPay Payroll API, to send the data a message like below must be constructed and posted to Create Employee Hourly Payments

{
  "organisationId": "a45272c5-14e0-42a3-833d-c30804dec81b",
  "employerId": "ad8dbe0e-3023-49a2-9fdc-0703a408c445",
  "employeeId": "d41eadf5-ac9b-47bd-8384-e0fd62cfd32d",
  "isRunValidationOnly": true,
  "isRemoveExistingHourlyPayments": true,
  "hourlyPayments": [
    {
      "rateName": "'Standard rate', 'Saturday overtime' etc ",
      "multiplier": 1,
      "dateOfEntry": "2024-04-13T00:00:00",
      "hoursWorked": 7.5
    }
  ]
}

• organisationId - The organisationId retrieved earlier

• employerId - The employerId retrieved earlier

• employeeId - The employerId retrieved earlier

• isRunValidationOnly - Before loading data it is advisable to run a validation check first (this is possible by setting the field isRunValidationOnly = true). If isRunValidationOnly is set to true the Payroll API does not save the hourlyPayments data but just runs the validation. Therefore it will give a strong indication if a request is likely to succeed or fail plus any likely error messages.

• isRemoveExistingHourlyPayments - Whenever a payslip has all the relevant data entered and the payroll administrator is happy the payslip is correct the payslip is “finalised”. “Finalised” means the payslip is closed and the next action is to pay the Employee the amount calculated on the payslip. On finalising a payslip the BrightPay application will copy over the pay details of the finalised payslip (including hourly payments) into the next payslip. This next payslip is the open payslip that the Payroll API will also write to. Copying the hourly payments is helpful if an administrator is manually entering payroll data, however when using the Payroll API to manage payslips this is usually undesirable. To remedy this when uploading Hourly Payments setting the field isRemoveExistingHourlyPayments = true will delete any Hourly Payments already in the payslip.

The EmployeeHourlyPaymentsRequest contains multiple HourlyPayments. The HourlyPayments contain

• rateName - This is a string representing the hourly rate (returned from GetEmployerHourlyRates field: hourlyRate.RateName)
• multiplier - if the hourlyRate.RateName is not set to "Standard rate" this must be set to 1.0, otherwise it can be used as a multiplier against the Employee's hourly payment rate in BrightPay (so if the employee is usually paid £20 per hour then a multiple of 1.5 will increase the rate to £30)

• dateOfEntry - this date is used to find the payslip to load the data into (this is not displayed on the payslip or stored in BrightPay). If the dates in the Timesheet align with the Employee’s payslip's period (e.g. you are loading data from timesheets for the 1st-7th of August and the Employee's payslip runs from the 1st-7th of August), then the Timesheet application can send the data as separate hourly payments for each date worked. The Employee will then see separate lines on their payslip for each day worked. A better approach if the TimeSheet data dates do not exactly match the pay period is to let the User select an indicative date (that can reflect the middle of athe desired BrightPay payslip time period). Next the Timesheet application could add up the hours at each rate and then send an HourlyPayment per rate (using the indicative date)

• hoursWorked - the number of hours worked at this hourlyRate

On success the system will return an a success message

{
  "isSuccess": true
}

If there are issues an error message will be returned (for more details see Managing Errors)

{
  "isSuccess": false,
  "apiErrors": [
    {
      "errorCode": "USERHASNOACCESSTOEMPLOYER",
      "errorHint": "The user account you are connecting with does not have access to the Employer."
    }
  ]
}

Then display the results back to the user.