Understanding Pay Instructions

This page describes the pay instruction and how you use them to control the generation of payments and deductions.

What is a Pay Instruction?

Pay instructions are pieces of information that relate to a single employee within the payroll. Instructions are used during the calculation to create pay lines. An instruction contains all the information necessary to calculate a deduction or payment.

There are many different types of pay instruction (to handle different types of calculations) but they all share some common properties. All pay instructions include a Start and End date [that indicate the scope of the instruction] and relate to a single employee.

Example Salary Pay Instruction

<?xml version="1.0"?>
<SalaryPayInstruction>
  <StartDate>2017-04-06</StartDate>
  <EndDate>2018-04-05</EndDate>
  <AnnualSalary>25500.00</AnnualSalary>
  <ProRataMethod>NotSet</ProRataMethod>
</SalaryPayInstruction>

Effective Instructions (aka the instruction scope)

Instructions are only effective for calculations that occur during the instruction scope. The scope is defined by the pay instruction start and end dates. The purpose of scope is to control the period of the instructions effectiveness.

An instruction must have a start date, but the end date is optional. Instructions without end dates are considered indefinitely effective.

Consider the following example:

Terry Tester is an employee with a regular monthly salary and he receives a salary payment every period. The instruction to control his salary is as follows:

<?xml version="1.0"?>
<SalaryPayInstruction>
  <StartDate>2016-04-01</StartDate>
  <AnnualSalary>24000.00</AnnualSalary>
  <ProRataMethod>NotSet</ProRataMethod>
</SalaryPayInstruction>

Terry also receives a one off bonus in May; the instruction for the bonus is as follows:

<?xml version="1.0"?>
<PrimitivePayInstruction>
  <StartDate>2016-05-01</StartDate>
  <EndDate>2016-05-31</EndDate>
  <Value>500.00</Value>
  <Code>BONUS</Code>
</PrimitivePayInstruction>

With these instructions in place, when calculating Period 1, only the salary instruction is effective, in period 2 both the salary and bonus are effective and in period 3 only the salary is effective once again.

alt text

Performing pay runs for all three months would resulting in the following pay lines.

Monthly Period 1 Monthly Period 2 Monthly Period 3
Salary Pay Line £2000 Salary Pay Line £2000 Salary Pay Line £2000
Bonus Pay Line £500
----------------------- ----------------------- -----------------------
£2000 £2500 £2000

The value of a salary pay instruction is divided equally between the annual payment periods. An employee paid in a weekly schedule would receive 1/52 of their salary, were as a monthly paid employee received 1/12 of their annual salary.

Consideration for Supplementary Runs

To avoid duplication of payments, special considerations are made during supplementary pay runs. If the calculation process detects the Pay Run is marked as supplementary, it checks to see if the instruction already has an associated pay line (for the period being calculated). If a pay line exists, then no further action is taken for that instruction. If no pay line is detected, then the instruction is included in the supplementary calculation.

Pay instructions that apply values based on period totals are always executed in supplementary runs. For example an income Tax Pay Instruction is used to calculate the taxable deduction on the entire gross payment. If a supplementary pay instruction changes the gross payment, then an additional tax pay line will be generated.

Modelling Change With Pay Instructions

The API is designed to handle rewind and replay behaviour. To accomplish this pay instructions are used to represent the history of the employee's payroll. Using the effective scope of pay instructions a complete history of the employee is recorded. With this history, it is possible to rewind and replay the pay runs to recalculate the historic results as needed.

Why is rewind and replay so important?

The truth is... mistakes happen.

Payroll is a complicated process and with complication comes the chance of making errors. Being able to rewind a payroll (to a previous point in time), make amendments and then replay it enables mistakes to be corrected without the need to re-enter the entire payroll history.

Consider the following example: Terry Tester joins the firm at the start of the tax year. However it takes some time before his previous employment tax code is advised. To begin with the API allocates Terry the default emergency tax code (2016/17 Emergency Tax Code is 1100L). In the second tax period, the correct tax code is received and a new Tax Pay Instruction is added. Amending the original instruction (to use the new tax code) would invalidate the calculation made in period 1. To handle this, the scope of the original tax pay instruction is reduced to period 1 only (by adding an end date) and a new tax instruction is added starting in period 2.

Original Instruction

Emergency Tax Pay Instruction

<?xml version="1.0"?>
<TaxPayInstruction>
    <StartDate>2016-04-06</StartDate>
    <TaxBasis>Cumulative</TaxBasis>
    <TaxCode>1100L</TaxCode>
</TaxPayInstruction>

Amended Instruction

Updated Original Tax Pay Instruction

<?xml version="1.0"?>
<TaxPayInstruction>
    <StartDate>2016-04-06</StartDate>
    <EndDate>2016-05-05</EndDate>
    <TaxBasis>Cumulative</TaxBasis>
    <TaxCode>1100L</TaxCode>
</TaxPayInstruction>

New Tax Pay Instruction

<?xml version="1.0"?>
<TaxPayInstruction>
    <StartDate>2016-05-06</StartDate>
    <TaxBasis>Cumulative</TaxBasis>
    <TaxCode>950L</TaxCode>
</TaxPayInstruction>

alt text

Year To Date Pay Instructions

Employment and payroll doesn't always fit neatly into the tax year. Sometimes additional information is required for periods before the payroll began. For situations where you need to add historic information, there are Year to Date Pay Instructions (YTD).

YTD instructions include a start and (optional) end date to control the period of effectiveness. But, unlike regular instructions, they can only ever generate a single pay line instance. They do not create a pay line instance for every effective period.

Another difference between regular and YTD instructions is how the resulting lines are generated. Regular instructions include the values needed to calculate the line values whereas YTD instructions include the pre-calculated line values.

At a glance differences between regular and YTD pay instructions.

Regular Pay Instruction YTD Pay Instruction
Period of effectiveness Controlled by start and (optional) end date Controlled by start and (optional) end date
Includes pre-calculated values false true
Can result in multiple pay lines true (one per effective period) false (there can only be one)

The following example shows the difference between a regular NI Pay Instruction and a YTD NI Pay Instruction. Note: the YTD instruction includes the pre-calculated NI band values.

NI Pay Instruction

<?xml version="1.0"?>
<NIPayInstruction>
    <StartDate>2016-04-06</StartDate>
    <EndDate>2017-04-05</EndDate>
    <DirCalculationMethod>Off</DirCalculationMethod>
    <WeeksAsDir>0</WeeksAsDir>
    <NILetter>A</NILetter>
</NIPayInstruction>

YTD NI Pay Instruction

<?xml version="1.0"?>
<NIYTDPayInstruction>
    <StartDate>2016-04-06</StartDate>
    <EndDate>2017-04-05</EndDate>
    <Value>-238.10</Value>
    <EmployerNI>-238.10</EmployerNI>
    <NIablePay>2000.00</NIablePay>
    <NILetter>A</NILetter>
    <LEL>123.99</LEL>
    <LELtoPT>123.99</LELtoPT>
    <PTtoST>123.99</PTtoST>
    <STtoUAP>123.99</STtoUAP>
    <STtoUEL>123.99</STtoUEL>
    <UAPtoUEL>123.99</UAPtoUEL>
    <UELtoUST>123.99</UELtoUST>
    <UELtoAUST>123.99</UELtoAUST>
    <AboveUST>123.99</AboveUST>
    <AboveAUST>123.99</AboveAUST>
    <RebateEE>123.99</RebateEE>
    <RebateER>123.99</RebateER>
    <DirCalculationMethod>Off</DirCalculationMethod>
</NIYTDPayInstruction>