Understanding PayOptions

PayOptions form the basis of your payroll. Before getting in to the specifics of the object, let's look at how it's used.
Employers have a property called DefaultPayOptions.
If you create a new Employee without setting the PayOptions property then the DefaultPayOptions from the Employer will be used (which you can then modify if you want to).
When you start a new PayRun it contains a PayRunEntry for each Employee along with the employees' PayOptions property.
You can modify the PayOptions property of a PayRunEntry without affecting the PayOptions property of the Employee .

Basic Pay

Four properties of the PayOptions model determine the basic pay amount of an employee.

`period`	`period` This property determines the frequency that you pay your employees. i.e., Monthly, Weekly, etc.
`payAmount`	`payAmount` The amount that the Employee is regularly paid each period
`basis`	`basis` If the `payAmount` is an `Daily` or `Hourly` rate then you should set this accordingly. If however it's a set amount for the period then leave this set to `Monthly`
`payAmountMultiplier`	`payAmountMultiplier` This property is irrelevant if the `basis` is `Monthly`. But if the `basis` is `Daily` or `Hourly` then this property sets how many days/hours the employee should be paid for in the period.

To illustrate the above, here are a few examples

Example #1

An Employee paid £3k each month for an annual salary of £36,000.

{
 ...
 "payOptions": {
  "period": "Monthly",
  "basis": "Monthly",
  "payAmount": 3000.00,
  "payAmountMultiplier": null,
   ...
 },
}

Example #2

An Employee paid weekly, typically for 40hrs a week, @ £15/hr

{
 ...
 "payOptions": {
  "period": "Weekly",
  "basis": "Hourly",
  "payAmount": 15.00,
  "payAmountMultiplier": 40,
   ...
 },
}

Example #3

An Employee paid monthly, on a day rate of £110, for 20 days a month

{
 ...
 "payOptions": {
  "period": "Monthly",
  "basis": "Daily",
  "payAmount": 110.00,
  "payAmountMultiplier": 20,
   ...
 },
}

The boolean property NationalMinumumWage property can only be set to true if the basis is Hourly.

If this is enabled then the PayAmount (which would be the hourly rate) has no effect. Instead we'll work out the appropriate minimum wage for the employee based on their age at the start of each pay run

Additions and Deductions

As well as the basic pay amount detailed above, you may want to add additional lines to deduct or add an amount to an employees pay. This is where the RegularPayLines property comes in.

RegularPayLines is an array of PayLines .
The three main properties of the PayLine are as follows:

`value`	`value` The amount to add or subtract (always use positive value)
`description`	`description` The description to appear on the payslip.
`code`	`code` The `Code` of a `PayCode` . The `PayCode` determines if this is an addition or a deduction and how the amount should be treated with regards to tax and NI.

Example

An Employee paid £3k/month with an added £50 bonus.

{
 ...
 "payOptions": {
  "period": "Monthly",
  "basis": "Monthly",
  "payAmount": 3000.00,
  "payAmountMultiplier": null,
  "regularPayLines": [
    {
      "value": 50.0,
      "description": "Performance bonus for October",
      "code": "BONUS"
    }
  ],
   ...
 },
}

Other Properties

PayOptions contains other important properties which should be self-explanatory from their names. Many of them are used to populate the FPS sent to HMRC. But important properties to note that affect the final pay calculations are those within the TaxAndNi object.
The Ordinal property is explained here.

Full Example

Below is a full Employee model with the PayOptions set.

Example Employee

An Employee with PayOptions set

{
 "personalDetails": {
  "title": "Mr",
  "firstName": "Benedict",
  "lastName": "Cumberbatch",
  "dateOfBirth": "1976-07-19",
  "gender": "Male",
  "maritalStatus": "Married",
  "address": {
   "line1": "221B Baker Street",
   "line2": "Marylebone",
   "line3": "London",
   "postCode": "NW1 6XE",
   "country": "England"
  }
 },
 "employmentDetails": {
  "payrollCode": "1",
  "starterDetails": {
   "startDate": "2018-04-01",
   "starterDeclaration": "A"
  }
 },
 "payOptions": {
  "period": "Monthly",
  "ordinal": 1,
  "basis": "Monthly",
  "method": "Credit",
  "payAmount": 3000.00,
  "payAmountMultiplier": null,
  "taxAndNi": {
    "niTable": "A",
    "studentLoan": "None",
    "taxCode": "1185L",
    "week1Month1": false
  },
  "fpsFields": {
    "hoursNormallyWorked": "LessThan16"
  }
 }
}

Recommended Approach

Our recommended approach to updating values on any model is to always GET the full model you want to modify, make changes to the JSON data and then PUT that data with the relevant API call.

Create an Employee

The Ordinal property