Integrating with Timesheet Data

A common use case scenario for PayRun.io API is to integrate with timesheeting or time and attendance systems, this has a number of benefits.

  • employee timesheet can be automtically pushed to payroll as soon as it is approved.
  • improved speed and efficiency as there is no manual process required to move data between systems.
  • reduced risk of human error.

Two pay instruction options exist:

  • Rate pay instruction (recommended)
  • Primitive pay instruction

Using the RatePayInstruction

The RatePayInstruction requires the most granular data to be provided but in return will be able to produce the most detailed payslip which will typically reduce the number employee queiries.

To use the RatePayInstruction effectivley you will need the following data:

  • Rate - the monetaray amount to be paid per unit.
  • RateUoM - the unit of measure for this payment (Minute, Hour, Day, Week, Month, Year).
  • Units - the number if units to be paid.

The gross payment for this instruction will then be calculated as Rate * Units. By default the BASIC payment code will be used, however this can be overriden with any other payment code defined in the employer such as OVERTIME. This done by setting the Code property on the instruction.

Payslip Description

All pay instructions provide the ability to override the pay line description that appears on the payslip. If no description is provided in the pay instruction then the default description is taken from the payment code.

The RatePayInstruction also supports variable subsitution so that the rate, number of units and the unit of measure can be displayed to clearly explain how the gross value was calculated.

Example Payslip

In this example the employee is paid hourly for 3 distinct acivities during the period, the data is pushed from the timesheeting system into 3 separate RatePayInstructions. These activities and their resulting payments are then itemised on the employee's payslip.

Rate Pay Instrunction 1

The employee is paid for a single day shift at a rate of £130.64 per day.

curl -X POST \
  'https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstructions"' \
  -H 'Accept: application/xml' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/xml' \
  -d '<?xml version="1.0"?>
<RatePayInstruction xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <StartDate>2018-04-15</StartDate>
  <EndDate xsi:nil="true" />
  <Rate>130.64</Rate>
  <RateUoM>Day</RateUoM>
  <Units>1</Units>
  <Description>Day Shift ({Units:N2} @ {Rate:N2} per {RateUoM})</Description>
</RatePayInstruction>'
curl -X POST \
  'https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstructions' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json' \
  -d '{
  "RatePayInstruction": {
    "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
        "StartDate": "2018-04-15",
    "EndDate": null,
    "Rate": "136.4",
    "RateUoM": "Day"
    "Units": "1"
    "Description": "Day Shift ({Units:N2} @ {Rate:N2} per {RateUoM})"
  }
}'

Rate Pay Instrunction 2

The employee is paid for a night shift lasting 10 hours at rate of £15 per hour.

curl -X POST \
  'https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstructions"' \
  -H 'Accept: application/xml' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/xml' \
  -d '<?xml version="1.0"?>
<RatePayInstruction xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <StartDate>2018-04-16</StartDate>
  <EndDate>2018-04-17</EndDate>
  <Rate>15.00</Rate>
  <RateUoM>Hour</RateUoM>
  <Units>10</Units>
  <Description>Night Shift ({Units:N2} @ {Rate:N2} per {RateUoM}))</Description>
</RatePayInstruction>'
curl -X POST \
  'https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstructions' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json' \
  -d '{
  "RatePayInstruction": {
    "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
    "StartDate": "2018-04-16",
    "EndDate": "2018-04-17",
    "Rate": "15.00",
    "RateUoM": "Hour"
    "Units": "10"
    "Description": "Night Shift ({Units:N2} @ {Rate:N2} per {RateUoM})"
  }
}'

Rate Pay Instrunction 3

The employee is paid overtime lasting 3 hours at rate of £17 per hour.

curl -X POST \
  'https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstructions"' \
  -H 'Accept: application/xml' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/xml' \
  -d '<?xml version="1.0"?>
<RatePayInstruction xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <StartDate>2018-04-18</StartDate>
  <EndDate>2018-04-19</EndDate>
  <Code>OVERTIME</Code>
  <Rate>17.00</Rate>
  <RateUoM>Hour</RateUoM>
  <Units>3</Units>
  <Description>Overtime ({Units:N2} @ {Rate:N2} per {RateUoM})</Description>
</RatePayInstruction>'
curl -X POST \
  'https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstructions' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json' \
  -d '{
  "RatePayInstruction": {
    "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
    "StartDate": "2018-04-18",
    "EndDate": "2018-04-19",
    "Code": "OVERTIME",
    "Rate": "17.00",
    "RateUoM": "Hour"
    "Units": "3"
    "Description": "Overtime ({Units:N2} @ {Rate:N2} per {RateUoM})"
  }
}'

The Payslip

Following a pay run calculation the employee's payslip would look similar to the example below with each payment itemised with the rate, units and unit of measure.

Payslip
  |------------------------------------- |------------- |------------------------------------- |------------- |
  | Payments                             | Amount £     | Deductions                           | Amount £     |
  |------------------------------------- |------------- |------------------------------------- |------------- |
  | Day Shift (1.00 @ 130.64 per Day)    | 130.64       | Tax                                  | 0.00         |
  | Night Shift (10.00 @ 15.00 per Hour) | 150.00       | National Insurance                   | 0.00         |
  | Overtime (3.00 @ 17.00 per Hour)     | 51.00        |                                      |              |
  |------------------------------------- |------------- |------------------------------------- |------------- |
  | NET PAY                              | 331.64       |
  |------------------------------------- |------------- |------------------------------------- |------------- |
  | This Period                          | Amount £     | Year to Date                         | Amount £     |
  |------------------------------------- |------------- |------------------------------------- |------------- |
  | Employer NI                          | 0.00         | Employer NI                          | 0.00         |
  | Employee NI                          | 0.00         | Employee NI                          | 0.00         |
  | Niable Pay                           | 331.64       | Niable Pay                           | 331.64       |
  | Taxable Pay                          | 331.64       | Taxable Pay                          | 331.64       |
  | Tax Paid                             | 0.00         | Tax Paid                             | 0.00         |
  |------------------------------------- |------------- |------------------------------------- |------------- |