Pensions supports many different pension configurations. This allows for pension contributions to be correctly calculated and included in the employee's payslips regardless of the type of pension being modeled.

Pensions also support the employers Auto Enrolment obligations.

Pension Objects

Pensions are implemented in an pattern that allows for employer level configuration with optional employee specific overrides.

This is controlled using two object types; Pension and Pension Pay Instruction.


The core details of the pension are described using the revisable pension object. This holds the global details of the pension scheme shared by all pension contributors.

See Pension reference data for more details.

Pension Pay Instruction

Membership of the pension scheme is controlled by the pension pay instruction. If an employee has a pension pay instruction in scope, they are considered members of the pension scheme.

See Pension Pay Instruction reference data for more details.

Pay Line Pension

The third element of the pension cohort is the Pension Pay Line. This line contains the calculated contribution values for the employer and employee and is generated for all employees who have an effective pension pay instruction within a pay run calculation.

See Pay Line Pension reference data for more details.


The pension object contains the default contribution values for the scheme. For example Employee Contribution Percentage. However, this value can be overridden in the Pension Pay Instruction for employees who have alternative contribution values.

Using this pattern of override, it is possible to model specific employee requirements within a common pension base scheme.

The Pension Controlling Objects

Employer Employee Pension Pension Pay Instruction Pension contributions ( Pay Line Pension )

Creating A Pension

Pension are created in the same way as other API objects, using [PUT] or [POST]. The following example demonstrates creation of a Nest based pension scheme (compatible for use with Auto Enrolment) using [POST].

curl -X POST \
  '' \
  -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"?>
<Pension xmlns:xsd="" xmlns:xsi="">
    <SchemeName>Nest Minimum Contribution</SchemeName>
curl -X POST \
  '' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json' \
  -d '{
    "Pension": {
        "EffectiveDate": "2018-04-06",
        "Revision": "0",
        "SchemeName": "Nest Minimum Contribution",
        "ProviderName": "Nest",
        "ProviderEmployerRef": "EmployerRef",
        "Group": "GroupName",
        "SubGroup": "SubGroup",
        "EmployeeContributionPercent": "0.01",
        "EmployerContributionPercent": "0.01",
        "TaxationMethod": "ReliefAtSource",
        "ProRataMethod": "NotSet",
        "AECompatible": "true",
        "SalarySacrifice": "false",
        "UseAEThresholds": "true",
        "PensionablePayCodes": {
            "PayCode": "BASIC"
        "QualifyingPayCodes": {
            "PayCode": "BASIC"

Some notes on the pension properties

  • AECompatible : Used to indicate that the pension can be used for Auto Enrolment.
  • UseAEThresholds : Determines if the pension excludes pensionable pay outside the Auto Enrolment thresholds.
  • PensionablePayCodes : The pay codes used to select which pay lines are included in the pensionable pay.
  • QualifyingPayCodes : The pay codes used to select the Auto Enrolment qualifying earnings.
  • ContributionPercent : The employee/employer contribution percentage expressed as a decimal fraction of 1.

Creating A Pension Pay Instruction

The pension scheme membership is controlled by the pension pay instruction. The instruction indicates which pension scheme the employee is a member of, employee overrides and any additional contributions.

Pension Pay Instructions are created in the same way as other API objects using [PUT] or [POST]. The following example demonstrates the creation of a Pension Pay Instruction starting on 6th April 2018 including an additional £100.00 employee contribution.

curl -X PUT \
  '' \
  -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"?>
    <Pension href="/Employer/ER001/Pension/PENSCH001" />
curl -X PUT \
  '' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json' \
  -d '{
    "PensionPayInstruction": {
        "StartDate": "2018-04-06",
        "AdditionalVoluntaryContributionCash": "100.00",
        "Pension": {
            "@href": "/Employer/ER001/Pension/PENSCH001"

Pension Tax Relief Methods

See the HMRC pensions advice page for more information on work place pensions. supports 2 types of pension tax relief; Net Based and Relief At Source. These options are set using the TaxationMethod property of the pension scheme.

Net Based (AKA Net Pay)

Pension schemes operating with Net Based relief deduct the pension contributions before income tax is calculated. This provides full tax relief at the highest rate for the employee. In a net based scheme, the employee gets tax relief on higher rate taxation. However, employees that do not pay tax do not benefit.

Relief At Source

When using the Relief At Source method, the pension takes 80% of the employees contribution from their salary and claims 20% back from the HMRC. In a relief at source based pension, all employees receive 20% relief. But higher rate tax payers still pay tax over 20%.

Some pension providers reclaim the relief directly from the HMRC others allow the employer to do so. To support this there are 2 types of Relief at source; Include and Excluded

  • Included - Indicates that the figure calculated includes the Relief At Source amount.
  • Excluded - Indicates that the calculated figure does not include the Relief At Source amount.

Salary Sacrifice

Some employers operate a Salary Sacrifice scheme. In this type of pension, the pension contribution is calculated before tax and national instance deductions. In this way the employer can save money on Employers National Insurance contributions, which are passed on to the employee via increased pension contributions.

In, salary sacrifice pension contributions appear as negative values on the payment side of the pay slip.


By default, pension contributions are calculated in alignment with the payment period. However, if an employee joins the scheme mid-period they may miss some contribution.

Some pension schemes allow for mid period joiners by supporting pro-rata calculations. Pro-rata options are set using the ProRataMethod pension scheme property.

See Pro-rata Calculation Methods for more information.

Cash and Percentage Contributions

There are two ways of calculating employee and employer contributions; Cash and Percentage.

  • Cash contributions are a fixed amount for each payment period.
  • Percentage contributions are calculated from the total pensionable pay.

Separate properties are provided (in Pension and Pension Pay Instruction) for employee and employer contributions. This allows for any mix of employer / employee contribution pattern.

Additional Voluntary Contributions

In addition to cash and percentage contributions, the employee can also opt to add a voluntary cash or percentage contribution. This value is added to the employee contributions all ready calculated using the standard cash or percent methods.

Pension Pay Codes

By default there are 3 standard pension pay codes that will appear in the generated pension pay lines. These system codes are specially setup to correctly support the reporting requirements of the pension scheme.

  • PENSION - This pay code is used for net based pensions.
  • PENSIONRAS - Used for relief at source pensions.
  • PENSIONSS - Used for salary sacrifice pension schemes.

The Pension and Pension Pay Instruction support the ability to override the default pension pay codes. However this should only be done by experienced users who understand the pension pay code requirements.


Don't override the default Pension pay codes unless you know what you are doing. Overriding the payment code may cause incorrect pension contribution calculations.