Follow this article to set up full integration using NEST web services.
There are two parts to the integration which operate independently:
- A Data feed that can fetch Opt-outs at the beginning of the pay cycle (like Tax codes).
- A submission report that will submit the information to NEST (like FPS and EPS)
Pre-requisites #
Before proceeding, you must ensure the NEST pension scheme has been set up correctly in Setup > Report Definitions:
- You must have the correct NEST Pension scheme Reference number starting EMPXXX. The import process inserts a fake value of EMP0001, which will fail!
- You must enter the right NEST Group and the right NEST Payment source. The import process inserts default values of My group and My source, which may need to be changed.
- The Prp Alignment (Tax or Calendar periods) and Pay Reference Period dates from the Pay schedule must match the NEST Schedule dates.
- Workers must have identical NI Numbers in NEST and paiyroll® – a single letter mis-typed will fail
- You must enter your credentials (see below)
- If you have any workers without NINOs, see below:
Workers without a National Insurance number and Alternative unique identifiers #
NEST uses Alternative unique identifiers and NI Numbers for each worker. Because paiyroll® uses different unique identifiers from your previous payroll software, when you first upload contributions, NEST will automatically attempt to change your previous unique identifiers to our new ones using NINOs. This will require all NINOs to be correct and present. If there are incorrect NINOs or missing NINOs, those workers’ unique identifiers will not be automatically changed, and the API submission will not work.
In this case, you will need to log into your NEST portal and edit the worker’s unique identifier. You will find the paiyroll® unique identifier (e.g. 123456/2025-01-02) in Documents > GB NEST contribution . You may need to use CSV upload in this case until the NEST changes have propagated through to the schedule.
Bureau Credentials #
If you are a Bureau, please add your NEST credentials in Setup > Credentials > Add > GB Enrol and Contribute, GB Nest Opt-out > Update
If you are an Employer, skip this step.
1. Opt-Out Data feed #
Setup > Report Definition > Add…
- Select your Company
- Select the GB Nest Opt-Out Template
- Enter your NEST Username and Password twice
- If you are a bureau, leave the credentials blank – instead, enter your agent credentials in Setup > Add credentials, which will be used for all clients
- Click auto-approve to automatically approve the contribution schedule for payment. If you don’t do this, you will need to log in to NEST and manually approve the schedule for payment.
- Click Add:
This data feed will appear along with the other data feeds and will be scheduled to run automatically by Payroll Debbie. You can also run it any time by pressing the Start button.
Verify Operation #
We recommend that when you first set this up, you select Dry run. You can then Start the data feed to see exactly what it will do and check everything is working correctly. Then disable Dry Run.
When an Opt-out is retrieved successfully, it automatically applies to the relevant worker’s AE pay item. The data feed automatically enters the opt-out information (Opt-out date, reference) for you.
2. Enrol and Contribute Report Definition #
Important: We strongly recommend retaining the standard CSV report definitions GB Nest member and GB NEST contribution if the API integration does not work. This will allow you to log into NEST and upload the files as a backup.
Setup > Report Definition > Add…
- Select your Company
- Select the GB Nest Enrol and Contribute Template
- Enter your NEST Username and Password twice.
- Normally, you will want all schemes to be selected, so do not select any schemes
- Decide if you want the schedule to be Auto Approved for payment so that you won’t need to log into NEST after submission
- Note: If any workers have missing NI Numbers, we recommend not setting Auto-Approve initially. This will allow you to log in to NEST after submission to verify that everything has worked correctly before approving the schedule. Once you know it’s working, you can turn it on for subsequent submissions.
- Click Add:
Verify Operation #
After you have added the report definition, you must do a pay run Redo. This will check that your paiyroll® NEST scheme settings match the settings on your NEST portal. The settings will include EMP reference number, payment Source and PRP dates.
In Pay Runs > View > Reports click on the NEST Enrol and Contribute View button and carefully check the first 2 tabs below. If everything has been set correctly. You should see Usable groups, Usable payment sources and Usable schedules:
If you do not see these three usable values, you will see an orange warning or red error, and the submission will not work! Check the log details and modify the NEST scheme in paiyroll® or the NEST settings to match.
Repeat the pay run Redo until you see a Green Success flag. The above validation is repeated every time you perform a pay run Redo.
The most common reasons for no usable schedule are:
- Frequency mismatch, e.g. Tax Monthly vs. Monthly
- Pay Reference Period (PRP) mismatch – the PRP is the one in which the pay date falls, not the one worked!
- Group or Payment source mismatch
- Scheme is being excluded from the Report Definition
If you cannot resolve these issues, we strongly recommend you delete the NEST Enrol and Contribute report definition and revert to using the standard CSV reports and contact paiyroll support for further assistance.
Submission #
When you approve the Pay run, the following will occur:
- Any new Member enrolments will be submitted
- The system will wait 30 minutes or longer, depending on the number of enrolments, for NEST to process the employees. This may take some days in the case of future enrolments as NEST will not accept future enrolments
- The system will then submit the Contributions
- If Auto-Approve is set, the schedule will be approved immediately for payment (usually by Direct Debit)
- All transaction information is recorded
- The next pay run will start
You may also wish to log into NEST to check that everything has been completed successfully.
Wait; Error; Pay run Exception reports taking too long #
If you are enrolling workers, the entire NEST report submission may take some time – for example, several hours or days. When this occurs, the pay run workflow will go into an error exception state, and the Pay run will show Wait:
The Pay run logs will show an Error: Payrun.bpmn#12345: reports taking too long.
A task will appear in My tasks, which allows you to handle the exception. Is it important that you verify that the NEST Enrol and Contribute report submission has completed all phases successfully? This may take several hours. For future enrolments, this will take days. Be sure the report has finished by checking that the Status is Done
Then resume the Pay run by:
- My Tasks
- Resume Submission as Payroll Approver
- You may need to assign the task
- Resume report submissions (any issues have been resolved)
Details of the above steps are here.
The Pay Run workflow will then be completed.
Errors #
Unprocessable Entity (422) #
The following credentials error is due to an incorrect Reference in a Pension Scheme:
Unable to verify credentials for reference EMP0001: Transport error: Unprocessable Entity (422), headers=('content-length'...Go to Company Setup > Pay Definitions and check for all NEST pension schemes (entering NEST in the Search box generally filters only NEST schemes). Update each NEST scheme and check/ change the Reference to your own EMP number. Finally, check and delete any imported schemes that use the default EMP0001 number, which you are not using (any uses of a scheme will be checked first, and you will be asked to confirm).
TransportError: Forbidden (403) #
This is likely due to the use of the wrong EMP number. Check that the Pay Definitions> Scheme Reference EMP number is correct.
The information you’ve entered for this member doesn’t match this schedule. Please check that the earnings period for this member matches this schedule. You should also check that the payment source or start date for this member matches this schedule. (IFC01645) #
This occurs when, for example, the National Insurance number on NEST differs from the NINO on payroll®. Establish and correct the appropriate NINO.