Understanding Pay Codes

What is a Pay Code?

A pay code describes how an individual payment or deduction should be treated by the tax calculation engine and subsequently reported. Pay codes have a 1:1 relationship with pay lines but as pay lines cannot be created directly they also have a direct relationship with pay instructions.

For example, a tax pay instruction when passed through the calculator will always result in a pay line that has a pay code type of TAX.

Warning

Pay codes have a direct impact on payroll calculations and if mis-configured could result in employees paying too much or too little tax.

If you are unsure of the tax treatment to use please seek advice from a payroll professional.

System Pay Codes

Every employer is preloaded on creation with the following "system" pay codes, the system pay codes are marked as read-only and only a subset of their properties can be changed; they cannot be deleted.

Code Type Description NIable Taxable Default Nominal
BASIC Payment Basic Pay yes yes Payroll Liability
NI Deduction National Insurance no no PAYE And NIC
NIADJ Deduction National Insurance Adjustment no no PAYE And NIC
PENSION Deduction Pension Contribution - Net Based yes no Pension
PENSIONRAS Deduction Pension Contribution - Relief At Source yes yes Pension
PENSIONSS Payment Pension Contribution - Salary Sacrifice yes yes Pension
SAP Payment Statutory Adoption Pay yes yes Payroll Liability
SAPOFFSET Payment Statutory Adoption Pay Offset yes yes Payroll Liability
SHPP Payment Statutory Shared Parental Pay yes yes Payroll Liability
SHPPOFFSET Payment Statutory Shared Parental Pay Offset yes yes Payroll Liability
SLOAN Deduction Student Loan Repayment no no PAYE And NIC
SMP Payment Statutory Maternity Pay yes yes Payroll Liability
SMPOFFSET Payment Statutory Maternity Pay Offset yes yes Payroll Liability
SPP Payment Statutory Paternity Pay yes yes Payroll Liability
SPPOFFSET Payment Statutory Paternity Pay Offset yes yes Payroll Liability
SSP Payment Statutory Sickness Pay yes yes Payroll Liability
SSPOFFSET Payment Statutory Sickness Pay Offset yes yes Payroll Liability
TAX Deduction Tax no no PAYE And NIC

Custom Pay Codes

You are free to create an unlimited number of custom pay codes for your employers, you have complete control over their tax treatment and reporting.

For example you may wish to create a pay code for paying employees overtime, typically this would look like this.

Code Type Description NIable Taxable Default Nominal
OVERTIME Payment Overtime yes yes Payroll Liability
curl -X POST
   https://api.test.payrun.io/Employer/ER001/PayCodes
   -H 'Content-type: application/xml'
   -H 'Accept: application/xml'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
-d '<?xml version="1.0"?>
<PayCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <EffectiveDate>2017-01-01</EffectiveDate>
  <Revision>1</Revision>
  <Code>OVERTIME</Code>
  <Description>Overtime</Description>
  <NIable>true</NIable>
  <Taxable>true</Taxable>
  <Territory>UnitedKingdom</Territory>
  <Region>NotSet</Region>
  <Type>Payment</Type>
  <Benefit>false</Benefit>
  <Readonly>false</Readonly>
  <NominalCode href="/Employer/ER001/NominalCode/NOM001" />
</PayCode>'
curl -X PUT
   https://api.test.payrun.io/Employer/ER001/PayCodes
   -H 'Content-type: application/json'
   -H 'Accept: application/json'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
-d '{
  "PayCode": {
    "EffectiveDate": "2017-01-01",
    "Revision": "0",
    "Code": "OVERTIME",
    "Description": "Overtime",
    "NIable": "true",
    "Taxable": "true",
    "Territory": "UnitedKingdom",
    "Region": "NotSet",
    "Type": "Payment",
    "Benefit": "false",
    "Readonly": "false",
    "NominalCode": {
      "@href": "/Employer/ER001/NominalCode/NOM001"
    }
  }
}'

To use a custom pay code in a calculation you need create Primitive Pay Instruction, then simply pass your new custom pay code along with a gross monetary value payable in the period.

curl -X POST
   https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstructions
   -H 'Content-type: application/xml'
   -H 'Accept: application/xml'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
-d '<?xml version="1.0"?>
<PrimitivePayInstruction xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <StartDate>2017-05-01</StartDate>
  <EndDate>2016-05-30</EndDate>
  <Code>OVERTIME</Code>
  <Value>300.00</Value>
</PrimitivePayInstruction>'
curl -X PUT
   https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayInstructions
   -H 'Content-type: application/json'
   -H 'Accept: application/json'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
-d '{
  "PrimitivePayInstruction": {
    "StartDate": "2017-05-01",
    "EndDate": "2016-05-30",
    "Code": "OVERTIME",
    "Value": "300.00"
  }
}'

In the case of overtime where you may have multiple overtime rates, you can reuse the same pay code but override the description on the primitive pay instruction to differentiate between the different rates paid to the employee on their payslip. Or if you prefer you can create seprarate custom pay codes for each variation of overtime, this would allow for more advanced reporting in the future should you wish to report on all "Overtime (x2 rate)" paid. Importantly the tax and NI treatment are identical.

Code Type Description NIable Taxable Default Nominal
OTIME2 Payment Overtime (x2 rate) yes yes Payroll Liability
curl -X POST
   https://api.test.payrun.io/Employer/ER001/PayCodes
   -H 'Content-type: application/xml'
   -H 'Accept: application/xml'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
-d '<?xml version="1.0"?>
<PayCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <EffectiveDate>2017-01-01</EffectiveDate>
  <Revision>1</Revision>
  <Code>OVERTIME2</Code>
  <Description>Overtime (x2 rate)</Description>
  <NIable>true</NIable>
  <Taxable>true</Taxable>
  <Territory>UnitedKingdom</Territory>
  <Region>NotSet</Region>
  <Type>Payment</Type>
  <Benefit>false</Benefit>
  <Readonly>false</Readonly>
  <NominalCode href="/Employer/ER001/NominalCode/NOM001" />
</PayCode>'
curl -X PUT
   https://api.test.payrun.io/Employers
   -H 'Content-type: application/json'
   -H 'Accept: application/json'
   -H 'Api-Version: default'
   -H 'Authorization: {OAuthHeader}'
   -H 'Cache-Control: no-cache'
-d '{
  "PayCode": {
    "EffectiveDate": "2017-01-01",
    "Revision": "1",
    "Code": "OVERTIME2",
    "Description": "Overtime (x2 rate)",
    "NIable": "true",
    "Taxable": "true",
    "Territory": "UnitedKingdom",
    "Region": "NotSet",
    "Type": "Payment",
    "Benefit": "false",
    "Readonly": "false",
    "NominalCode": {
      "@href": "/Employer/ER001/NominalCode/NOM001"
    }
  }
}'