Payroll run
This guide shows how your application should use the Payroll Integration API during the regular payroll run. At the end of each payroll run your application should build a contributions request that includes the details of every employee that is a member of the pension scheme. You can help to ensure the contributions request is correct by checking for changes in the account information that we make available to you, and applying these changes to the payroll under the customer’s guidance. By doing this you will reduce the chance of the contributions having errors in them.
Key concepts
Our Payroll Integration API exposes two main entities to describe the pension contributions from a payroll run. One is the pay reference period that the contributions are made in, and the other is the employees who are the members of the scheme.
The pay reference period is the period in which the payroll is being run, defined by its start and end dates. Typically the pay reference period will be the same as the payroll period, but some payrolls pay their staff weekly and settle their pension contributions at the end of the month, an arrangement we refer to as “Weekly-Monthly”. The frequencies of the pay reference period and the payroll period are both included in the account information.
Every request to the contributions operation includes the pay reference period that the contributions are made in. Consecutive submissions must be for consecutive periods of time: for a weekly payroll you might make a contributions request covering the 1st to the 7th at the end of the payroll run for that week, then one for the 8th to the 14th at the end of the next payroll run.
Every request to the contributions operation must also include all of the employees who are a member of the pension scheme during the pay reference period. Part of the information you send us about each employee is a unique identifier, which should be a unique value that your application uses to refer to that specific employee. A payroll or works number would be ideal for this. We will use the unique identifier you give us to refer to the employee in other parts of the Payroll Integration API, such as the account opt-outs operation.
Exclusions and restrictions
The Payroll Integration API validates your contributions request and then queues it for processing. The API does not support more than one contributions request (for the same account and different pay reference periods) being in the processing queue at one time. You should allow time for a file to process before submitting another file.
Before you start
The customer must authorise your application to use the Payroll Integration API on their behalf, if they haven’t done so already. You must also have established the admin account number, as described in the account set up guide.
The last step in the account set up guide is to retrieve the account information from the Payroll Integration API and compare it with the way your payroll is set up. This is also the first step you should carry out in the payroll run. For the first payroll run you may be able to combine these two activities if the user can proceed from account set up into their first payroll run.
Retrieve account information
At the beginning of each payroll run you should make a request to the account information operation and act on any changes to the account:
- Make sure the
nextPayReferencePeriodmatches the period you expect the next payroll run to cover. - Apply any changes to worker group contribution levels or amounts to the employees that belong to the worker group.
- Update the names of any entities that have changed, such as the account name or the worker group description.
Any changes in the account information will be as a result of the customer making the change in employer Online Services, or by contacting our support team to make the change. You should make sure any differences between the account information we return and the information for the payroll are resolved before the payroll run.
Retrieve opt-outs
Employees can notify The People’s Pension that they want to opt-out of the pension scheme, once they have been enrolled. The account opt-outs operation provides a list of those employees who have opted-out. Your application should offer to apply these opt-outs to the payroll for the customer.
The location of the account opt-outs operation for an account can be found in the links.opt-outs property in the returned JSON document. Retrieve the opt-outs by making an HTTP GET to the location, for example:
GET /api/v2/accounts/855969/opt-outs HTTP/1.1
Host: api-sandbox.peoplespartnership.co.uk
Authorization: Bearer SlAV32hkKG
(Substituting a valid admin account number and access token.)
In response you get a document like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"type": "accountOptOuts",
"id": "855969",
"attributes": {
"optOuts": [
{
"uniqueId": "65775",
"forename": "Laura",
"surname": "Thomas",
"niNumber": "HA850971A",
"optOutDate": "2017-06-22",
"refundStatus": "No Refund",
"optOutChannel": "Telephone",
"employeeRefund": 0,
"employerRefund": 0
},
{
"uniqueId": "65309",
"forename": "Oliver",
"surname": "King",
"niNumber": "MS324441B",
"optOutDate": "2017-06-24",
"entitledToRefund": "Processed",
"optOutChannel": "Paper",
"employeeRefund": 101.45,
"employerRefund": 101.45
}
]
}
},
"links": {
"self": "https://api-sandbox.peoplespartnership.co.uk/api/v2/accounts/855969/opt-outs",
"account": "https://api-sandbox.peoplespartnership.co.uk/api/v2/accounts/855969"
}
}
The opt-out response includes the employees from the contributions request, including the unique identifier and National Insurance number. These values can be used to identify the employee within the payroll.
The opt-out response also gives the amount of any refund due to the employee and employer as a result of the opt-out. It can take a number of days to calculate and process the refund; the state of the process is described by the entitledToRefund and refundStatus fields. Your application should request the account opt-outs and check the state of the process periodically.
On the very first payroll run there can be no opt-outs as there are no members of the scheme. In this case you could skip this step of the process.
Submit contributions
After the payroll run your application can prepare the contributions request, which you use to send us the details of the contributions made by each member of the pension scheme. The contributions request is how you tell us the amount contributed by the employer and employee to the pension scheme of each employee.
The contributions request also includes the personal details of every active scheme member. Any employee in the contributions request that we have no previous record of is taken to be joining the scheme: we will send them joiner information setting out their contributions based on the worker group that they are a member of. The joiner information also tells them how to opt out of the scheme if they would like.
Any employee that we have a previous record of and is missing from the contributions request is taken to be a scheme leaver. If an employee is not making a contribution in a particular pay reference period they must appear in the contributions request with zero for their contributions.
Changes to an employee’s personal details can also be notified to us through the contributions request. We will identify any changes and apply them to the account.
You must make sure the pay reference period dates in the contribution request match those we expect, as returned in the nextPayReferencePeriod field of the account information response. You must also ensure that the workerGroupId for each employee names an active worker group, taking into account the effective dates of each worker group.
The contributions request looks like this:
POST /api/v2/contributions HTTP/1.1
Host: api-sandbox.peoplespartnership.co.uk
Authorization: Bearer SlAV32hkKG
{
"data": {
"type": "contributions",
"attributes": {
"accountId": 654321,
"payReferencePeriod": {
"start": "2017-04-17",
"end": "2017-04-30"
},
"employees": [
{
"title": "Mrs",
"gender": "F",
"forename": "Abigail",
"middleName": "",
"surname": "Williamson",
"dateOfBirth": "1985-01-10",
"niNumber": "HM302274C",
"uniqueId": "851001",
"address": {
"line1": "99 Old Edinburgh Road",
"line2": "Beedon",
"line3": "Newbury",
"line5": "RG20 8JR"
},
"mobilePhoneNumber": "07043090072",
"personalEmailAddress": "AbigailWilliamson@rhyta.com",
"employmentPeriod": {
"start": "2004-04-13"
},
"workerGroupId": "UF",
"autoEnrolmentStatus": "Eligible",
"autoEnrolmentDate": "2017-04-21",
"pensionableEarnings": 1818.06,
"employerContributionAmount": 54.54,
"employeeContributionAmount": 90.9
},
/* Additional employees omitted */
],
"total": 463.6
}
}
}
(Additional employees omitted; a complete example can be found in the API reference.)
Check for contribution status
The successful response to a contributions request is an HTTP 202 status code with a contributionsStatus document. The document includes Boolean fields to indicate which phases of processing have been carried out:
HTTP/1.1 202 Accepted
Content-Type: application/vnd.api+json
Location: https://api-sandbox.peoplespartnership.co.uk/api/v2/contributions/3699f346-326f-46ab-9b6d-f1313ecc0bdc/status
{
"data": {
"type": "contributionsStatus",
"id": "3699f346-326f-46ab-9b6d-f1313ecc0bdc",
"attributes": {
"received": true,
"validating": false,
"accepted": false,
"failed": false,
"processed": false,
"nextPollAfter": "2017-08-04T16:45:10Z"
}
},
"links": {
"self": "https://api-sandbox.peoplespartnership.co.uk/api/v2/contributions/3699f346-326f-46ab-9b6d-f1313ecc0bdc/status"
}
}
The contributions will start in the ‘received’ state, followed by ‘validating’ before reaching either ‘accepted’ or ‘failed’. If the contributions reach ‘accepted’ state then they have been validated and will be processed. After processing they reach the ‘processed’ state, at which point the contributions have been successfully applied to the account.
If the contributions reach the ‘failed’ state, an ‘errors’ link will be added to the ‘links’ object; the target of this link will return a JSON API errors document, described below. Contributions only reach the ‘failed’ state after validation: once accepted for processing the contributions file will not fail to be processed.
The contributionsStatus response also includes the canonical location of the status operation in the Location header and also in the self link in the JSON API document. You can check the status of submitted contributions by making an HTTP GET request to this URL, but you should do so no sooner than the time provided in the nextPollAfter field.
Retrieve errors
If the contributionStatus response shows that the contributions failed validation you will be able to retrieve a collection of errors from the errors link. For example:
GET /api/v2/contributions/9a1665d4-0b3d-4d9c-99e0-87db26ea5518/errors HTTP/1.1
Host: api-sandbox.peoplespartnership.co.uk
Authorization: Bearer SlAV32hkKG
The response to which will resemble:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"errors": [
{
"id": "a52b9b7c-2f17-4ea1-8721-6abb0f18fd11",
"code": "D/B03",
"title": "The provided gender indicates Female; however provided title indicates Male",
"meta": {
"uniqueId": "220568",
"providedValue": "F",
"expectedValue": "",
"employeeIndex": "4",
"category": "DetailsRecord"
},
"links": {
"about": "https://developer.peoplespartnership.co.uk/errors/d-b03/"
}
}
]
}
Each error includes the uniqueId of the employee whose information caused the validation error.
Testing opt-outs
To recreate the opt-out process you will need to email your request to your payroll relationship manager who will advise and assist you on the process.