Building an integration with PensionSync will create a seamless, end-to-end pension experience for your customers without actually building your own pension data exchange with multiple pension providers.
Follow our guide below to understand your integration options and get started with integrating with PensionSync. This guide is built primarily for payroll integrations, but may be used to guide through middleware or softwares. If you feel something is missing from this guide, please email the support team (support@pensionsync.com) with your query.
Please register on our Developer Portal to generate your Sandbox API keys.
The following steps will show the available destinations and the associated active methods that you can try out:
You should get the results in the 'Response Body' section where you'll find all the available destinations and the associated active methods.
Please remember to always press the 'Create Authorisation Header' button before calling any method.
Once you have created your keys, please email the support team to confirm email addresses for anyone who would require access to the Software Developer Help Centre. This area of our help centre is specifically aimed at software developers, and is password protected to ensure end users don’t stumble into the technical detail of an API integration, hence the need to be invited by us to access the documentation.
Right, you’ve got your API keys, so now we need to look at the API calls themselves.
We use OAuth 1a with a 1 legged flow (sometimes called 0 legged). This means that it is essentially a client-server authentication on each call.
Where possible we recommend using an existing library for your platform as there are quite a few ways to get the signature wrong if doing it from scratch. Most platforms have a mature OAuth 1 library.
If you need to do it from scratch please follow the below example.
Example: https://pensionsync.zendesk.com/hc/en-us/articles/360003752317-OAuth-step-by-step-example
It should also be noted that PensionSync uses two very well tested (and unrelated to each other) 3rd party OAuth libraries. One is used by the live docs swagger page the other by the PensionSync backend.
If you are getting signature issues with your own implementation it is highly likely you are missing some small detail rather than there being an issue with those libraries, so hopefully the example will help.
An intermediary can be thought of as the entity which is employing users to operate the Payroll Software. For example, an Intermediary could be the Employer with inhouse payroll staff, or a Payroll Bureau which is operating Payroll Software to perform payroll services for multiple Employers. Many of PensionSync’s functions require an intermediaryId to be passed as a parameter in order to operate.
API call: POST /api/admin/intermediary
Creates an intermediary in PensionSync. Returns a unique intermediaryId generated by PensionSync. This should be stored (preferably non-amendable by the end user) by the integrating software for use in further API calls for the user.
When creating the intermediary, the 'name' field is mandatory. The 'name' field is used in the PensionSync reporting, so that usage per intermediary can be identified by the PensionSync customer.
It is suggested that the name field is a combination of a unique code (such as a client reference number) that is recognisable to the payroll software provider plus the company name (bureau or inhouse employer, as operates the payroll).
The PensionSync Dashboard is where the user can see an overview of all their schemes and submissions that are processed through PensionSync. We have a YouTube video showing an overview of the user functionality:
https://www.youtube.com/watch?v=DKKm-I7AaqY&t=5s
The PensionSync Dashboard is available via a one time, time limited URL associated with a unique intermediaryId. The use of the one time, time limited URL means that a secure and authorised session with the Dashboard can be opened without the need for separate username/password credentials.
Use the employer/bureau’s intermediaryId with the API call:
POST /api/admin/intermediary/{intermediaryId}/smtAuthorization
And open the URL that is returned in the response body
The user has the option of adding their own external login to the Dashboard if they wish, but the ability to open the Dashboard from within payroll using the intermediaryId should be readily available to the user.
It is at this point that you have a number of options open to you depending on how automated a pension solution you require. This can be an evolving process, as further APIs can be added at any time to increase the automation within your software.
If you do not want your users to be able to submit the member data directly from payroll, then this is where the integration can stop.
As long as you have facility in your software for the users to:
Then your clients can open the PensionSync Dashboard and upload the PAPDIS file to the full range of our linked Pension Providers.
The steps below form the basis for a fully automated integration from payroll to pensions. The steps do not all need to be completed, you have the choice of which aspects you want to include in your software, and even have the option to add the later steps in future updates to the software.
Steps 5, 6 and 8 are recommended as minimum requirements for an automated solution - those being the ability to link the scheme from within payroll, submit the member data and retrieve opt outs.
Steps 7 and 9 definitely add to the automated flow but can be equally achieved by signposting the PensionSync Dashboard to the user, where they can see the success/errors from the member data submissions and review the pension scheme information (tax relief type, Groups etc).
Payroll often holds the pension scheme reference number, as this has to be output on most pension CSV files, this same identifier can then be used to connect your payroll software to the client’s pension provider using the ‘Post Scope’ API.
POST /api/admin/intermediary/{intermediaryId}/scope
The API requires the intermediaryId and the details for the pension scheme that the user wants to link to:
- employerId - the scheme reference number for the particular employer’s scheme
- destinationId - the three character code representing the pension provider
The response body for the call, returns an authorisation URL to the user, this should be opened for the user to confirm their pension provider credentials (as they would use to login to the particular scheme on the pension provider website).
You can call the following API to check if the authorisation is in place (this can be used at any point too - e.g. ahead of the user submitting the PASS member data):
GET /api/admin/intermediary/{intermediaryId}/employer/{employerId}/destination/{destinationId}/scopeAuthorization
Example process and further details are shown on:
https://pensionsync.zendesk.com/hc/en-us/articles/360003760017-Authorisation-Gateway
The big one, the ability to send the member data to the pension provider in one single format covering up to 6 pension providers. No logging into different pension provider websites.
There are a couple of options for the data that you can send us, which may depend on what you already produce in payroll for your clients.
If you already produce a PAPDIS CSV extract (perhaps for Smart Pension?) as one of your pension files, then it’s straightforward to send us the PAPDIS CSV via our API:
POST /api/submission/intermediary/{intermediaryId}
If you are unsure whether you already produce a PAPDIS file, you can review the specification here (https://pensionsync.zendesk.com/hc/en-us/articles/360020180618-PAPDIS-versions-1-0-and-1-1)
The Member Maintenance And Contributions method is a POST of PASS V1.1 data to PensionSync. The destinationId (see Step 5 above) of the data must be provided as a parameter to the method so that PensionSync can engage the correct data validation algorithms for that destination.
POST /api/membermaintenance_and_contributions/{destinationId}
The method returns a jobId (a unique identifier) for every data document posted to it via the upload method. The jobId can be used to interrogate the Job method to obtain a status on the progress of the uploaded document through PensionSync.
The PASS XSD is available on our help centre.
We recommend providing all data items to PensionSync for all destinations, rather than trying to build each individual pension providers requirements
When testing in Sandbox, payroll can use the 'doNotDeliver' flag in the header as follows:
The field documentId (in the API parameters, plus near the end of the file in PASS) is your reference to the submission, usually involving a reference to the client and the date/time stamp of the submission. The use of this identifier enables PensionSync to achieve idempotency for document uploads. Therefore even if there is a network error between the API consumer and the PensionSync API or an unexpected HTTP error code is received then the upload can be reattempted with an identical PASS document and documentId.
The PensionSync Dashboard will show all submissions - successes and errors - for the users, but a number of softwares also choose to show the results in payroll, in a similar manner to RTI successes/errors for a particular pay period.
On submitting the member data (step 6 above) a jobId is returned to you in the response body. This can be used to retrieve both the status of the job and, should there be any, any error messages:
Retrieve the job status: GET /api/job/{jobId}
Retrieve any error messages: GET /api/job/error/{jobId}
Information about the different job statuses is available on our help centre.
You’ve enrolled members and now some of them choose to opt out (employees opt out with the pension provider shortly after being enrolled, and are due a refund in payroll) or cease contributions (stop contributing, existing pot remains invested with the pension provider, no refund due).
We provide the data back to payroll to enable you to update the opt outs and cessations directly in payroll, via the Worker Instruction APi call
GET /api/worker_instruction/v2/{intermediaryId}/destination/{destinationId}/employerId/{employerId}
The different types of member data brought back from the providers is summarised in our help centre.
As well as accepting member data in a single format, we also output scheme data in a single format (SASS). This can be of assistance to software and end users as the scheme data can be used to bring back a number of key fields directly into payroll, helping not only the pension processing, but also ensuring the correct tax treatment on the pension contributions.
Scheme data can be collected by using the API call:
GET /api/scheme/{intermediaryId}/destination/{destinationId}/employerId/{employerId}
Further information and a scheme (SASS) XSD is on the help centre.
