Building your integration with PensionSync

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.

Step 1

Create API key (Sandbox)

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:

  1. Sign In to the Developer Portal and proceed to the Applications page
  2. Select your application and copy your developer portal credentials (Client ID and Client Secret)
  3. Go to the API Documentation page and key in your credentials
  4. Select the 'Destination Information' method and press 'Create Authorisation Header'
  5. Press 'Try it 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.

Step 2

PensionSync OAuth

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.

Step 3

Create IntermediaryId

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).

Step 4

Launch PensionSync Dashboard

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.

Options

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.

A - Basic No Frills Integration

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:

  1. Open the PensionSync Dashboard
  2. Create and download a PAPDIS CSV file - specification available here

Then your clients can open the PensionSync Dashboard and upload the PAPDIS file to the full range of our linked Pension Providers.

B - Automated Data Delivery

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).

Step 5

Link the pension scheme and authorise

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

  • AVC - Aviva
  • LGS - Legal & General
  • NOW - NOW: Pensions
  • NST - Nest
  • SMP - Smart Pension
  • TPP - The People’s Pension

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

Step 6

Submit member data

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.

Send PAPDIS CSV

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)

Send PASS XML or CSV

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

Testing PASS or PAPDIS

When testing in Sandbox, payroll can use the 'doNotDeliver' flag in the header as follows:

  • submit data to PensionSync with 'doNotDeliver' set to 'true'. This will result in PensionSync validation only being performed, the data will not be sent to the destination. This stage may need repeating until no further data errors exist.
  • once ready for end-to-end testing, submit data to PensionSync with 'doNotDeliver' set to 'false'. The data will then be processed by PensionSync and sent to the destination. 
  • Please note that doNotDeliver should always be set to false for live submissions, or PensionSync will not deliver your live data.

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.

Step 7

Retrieve job and error details

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.

Step 8

Retrieve Opt outs

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.

Step 9

Retrieve Scheme information

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.