Data Provisioning Service

The Data Provisioning Service (DPS) is provided by HMRC as a means of electonically delivering notices to employers. The service allows the secure retrieval of structured messages that are machine readable and can be processed and acted upon by the consuming application.

The PayRun.io encapsulates DPS (for PAYE) into a service that can both retrieve and process messages automatically for employers.

The use and behaviour of the DPS service is controlled via the DPS Job Instruction.

Inserting a DPS Job

After inserting a new job instruction, you receive a link to the jobs information page. Using this link, it is possible to monitor the job progress. For more details on jobs and their management see jobs page.

Using the example configuration below the job will download and apply all messages available for the employer in the current tax year. More granular behaviour can be invoked by using the MessageTypes and MessagesToProcess properties.

For the DPS call to be successful the linked Employer must have valid credentials set in their HMRCSettings. Credentials are issued by HMRC to the employer or agent.

curl -X POST \
  'https://api.test.payrun.io/jobs/payruns' \
  -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"?>
<DPSJobInstruction xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <HoldingDate xsi:nil="true" />
  <Retrieve>true</Retrieve>
  <Apply>true</Apply>
  <FromDate>2018-04-06</FromDate>
  <Employer href="/Employer/ER001" />
  <MessageTypes>P6,P9,SL1,SL2,AR,NOT,RTI</MessageTypes>
</PayRunJobInstruction>'
curl -X POST \
  'https://api.test.payrun.io/jobs/payruns' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json' \
  -d '{
  "PayRunJobInstruction": {
    "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
    "HoldingDate": null,
    "Retrieve": true,
    "Apply": true,
    "FromDate": "2018-04-06"
    "Employer": {
      "@href": "/Employer/ER001"
    },
    "MessageTypes": {
      "Type": [
        "P6","P9","SL1","SL2","AR","NOT","RTI"
      ]
    }
  }
}'

Accessing the Retrieved Messages

All retrieved messages for an employer can be accessed through the DpsMessage endpoints.

There is also a built in system report DPSMSG that can be used to more conveniently filter and return full messages. The example returns all P6 and P9 messages for the tax year with a status of Unresolved, this could be useful for managing exceptions.

curl -X GET \
  'https://api.test.payrun.io/report/DPSMSG/run?EmployerKey=ER001&FromDate=2018-04-06&ToDate=2019-04-05&MessageTypes=P6,P9&MessageStatuses=Unresolved' \
  -H 'Accept: application/xml' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/xml'
curl -X GET \
  'https://api.test.payrun.io/report/DPSMSG/run?EmployerKey=ER001&FromDate=2018-04-06&ToDate=2019-04-05&MessageTypes=P6,P9&MessageStatuses=Unresolved' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json'

Message Types

The DPS supports a variety of different messages types; the table below details the supported message types, their purpose and the automatic "apply" action.

Message type schemas and XSLT stylesheets are provided by HMRC on their website.

Message Type Description Apply Action
P6/P6b/P9 A coding notice detailing an employee's tax code, previous pay and tax. Where not already set the employee's tax instruction will be updated with the new tax code. Also a YTD tax adjustment will be created to reflect the correct tax position.
SL1 The SL1 start notice is issued to inform an employer they are required to start deducuting student loan repayments from the employee. Where not already set, a student loan pay instruction will be created for the employee.
SL2 The SL2 stop notice is issued to inform an employer they should stop deducuting student loan repayments from the employee. Where a matching, open student loan instruction is found it is ended using the provided stop date.
AR Employer annual reminders to employers; can contain messages AR6, AR1n, AR2n, AR1mn and AR2mn Information only.
NOT Employer notifications; can contain messages P35, P11d and incentive notifications Information only.
RTI Contains general notifcations for information only. NOT and NVR messages to correct or verify an employee's national insurance number. Where applicable NOT and NVR messages will update employee records with the correct national insurance number.

Managing Messages

Messages are managed through a series of statuses, in the scenario where you retrieve but do not apply, all messages will be saved with the status Retrieved.

Messages, or specific groups of messages, can be individually applied by issuing a specific DPS job instruction.

curl -X POST \
  'https://api.test.payrun.io/jobs/payruns' \
  -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"?>
<DPSJobInstruction xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <HoldingDate xsi:nil="true" />
  <Retrieve>false</Retrieve>
  <Apply>true</Apply>
  <Employer href="/Employer/ER001" />
  <MessagesToProcess>
    <Message href="/Employer/ER001/DpsMessages/DPS001" />
    <Message href="/Employer/ER001/DpsMessages/DPS002" />
  </MessagesToProcess>
</PayRunJobInstruction>'
curl -X POST \
  'https://api.test.payrun.io/jobs/payruns' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json' \
  -d '{
  "PayRunJobInstruction": {
    "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
    "Retrieve": false,
    "Apply": true,
    "Employer": {
      "@href": "/Employer/ER001"
    },
    "MessagesToProcess": {
      "Message": [
        {
          "@href": "/Employer/ER001/DpsMessages/DPS001"
        },
        {
          "@href": "/Employer/ER001/DpsMessages/DPS002"
        }
      ]
    }
  }
}'

Equally messages can be manually updated using a PUT or PATCH request against the individual message resource.

curl -X PATCH \
  'https://api.test.payrun.io/Employer/ER001/DpsMessage/DPS001' \
  -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"?>
<DpsMessage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <MessageStatus>Applied</MessageStatus>
  <ProcessingResult>This message has been manually updated.</ProcessingResult>
</DpsMessage>'
curl -X PATCH \
  'https://api.test.payrun.io/Employer/ER001/DpsMessage/DPS001' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json' \
  -d '{
  "PayRunJobInstruction": {
    "MessageStatus": "Applied",
    "ProcessingResult": "This message has been manually updated."
  }
}'

Testing the Service

The service can be tested im our test enviroment by using TaxOfficeNumber of 123 and any of the following TaxOfficeReference values in your employer HMRCSetting. You must also use valid test gateway credentials.

  • AN64312
  • 1739465
  • A6