v2.7 Page 1 of 12 13/11/2018

Data Provisioning Service (DPS): Supplementary Guidance and

How to use the DPS test service

v2.7 Page 2 of 12 13/11/2018

1. How to use the DPS service

The DPS API Specification published within the technical specifications contains instructions on the operation of the Data Provisioning Service. Development will involve:

programmatically posting an XML call for the DPSrequestToken message using the WSDL file dpsauthentication.wsdl. This will return a security token to be passed with all subsequent method calls within a 4 hour session

then programmatically posting XML method calls (including the token retrieved from the authentication call) for the following:

DPSquery - this is the method called to obtain the number of data items waiting to be retrieved. DPSretrieve - this is the method called to retrieve data from the DPS test service. DPSdate2index - this is the method used to convert a calendar date, meaningful to the employer or agent, into a high water mark prior to that date.

You will receive an appropriate XML response for any particular method call as defined in the DPS API Specification or the Response Error Messages document.

2. WSDLs and submission URLs For DPSrequestToken calls, the technical specifications contain a WSDL file named dpsauthentication.wsdl. The <soap:address> within this WSDL file should be changed as follows in order to make calls to the Third Party Validation Service (TPVS) and live environments: TPVS test service: <soap:address location="https://www.tpvs.hmrc.gov.uk/dpsauthentication/dpsauthentication.jws” /> Live: <soap:address location="https://dps.ws.hmrc.gov.uk/dpsauthentication/service" /> For subsequent method calls, the technical pack contains a WSDL file named dps.wsdl. The <soap:address> within this WSDL file should be changed as follows in order to make calls to the TPVS test service and live environments: TPVS test service: <soap:address location="https://www.tpvs.hmrc.gov.uk/dps/dps.jws" /> Live: <soap:address location="https://dps.ws.hmrc.gov.uk/dps/service” />

v2.7 Page 3 of 12 13/11/2018

3. Schemas

The technical pack contains a schema for each of the message types that can be retrieved from the DPS. These define the structure and content of the outbound XML messages. In a small number of instances you may find the data contained within fields does not match the specific patterns included within the published schemas. The field names and structure of the outgoing messages retrieved from the DPS will be compliant with the published schemas. DPSretrieve calls: PAYE For DPSretrieve calls with a dataType of P6, P9, SL1, SL2, PGL1 or PGL2, the responses will conform to only one corresponding schema in the ZIP archive “Outgoing schemas”. AR, NOT and RTI DPSretrieve calls each have more than one schema associated with the responses. For dataType RTI, where there is data to retrieve, the responses will conform to:

RTINotif, in the ZIP archive “Outgoing schemas”, or

the schemas in the “Generic Notification schemas”, or

a mixture of the two. DPS-enabled software will, therefore, need to be able to recognise and handle responses containing a mixture of RTI Notifications and Generic Notifications. DPSretrieve calls: Construction Industry Scheme (CIS) DPSretrieve calls with a dataType of CIS will conform to the schemas in the “Generic Notifications schemas”.

4. Stylesheets

P6, P6B, P9, SL1, SL2, PGL1, PGL2, AR, NOT or RTI messages retrieved from the DPS can be viewed and/or downloaded in XML format. The technical pack contains XSLT stylesheets that allow the P6, P6B, P9, SL1, SL2, PGL1, PGL2, AR and NOT forms to be rendered into a human readable format. Stylesheets are not available for the RTI messages or for any Generic Notifications.

5. Response Error Messages

If a DPS call fails validation, the error will be returned as a Soap fault. These faults are described within the Response Error Messages document within the technical specifications.

v2.7 Page 4 of 12 13/11/2018

6. RTI Notifications

RTI Notifications using RTINotif-vN-N.xsd The RTI Notification messages will include a FormType attribute of “NVR” to identify whether the Notification originated following submission of a NINO Verification Request (NVR) or “NOT” if the Notification was generated following submission of an Employer Alignment Submission (EAS) or Full Payment Submission (FPS). This will allow third-party software to filter the responses, if necessary, to allow them to be matched to the incoming submission.

Element/Attribute Cardinality Description

RTINot 1..1 This is the root XML element containing the generic notification. Each call to DPS can return multiple RTINot messages within a single <DPSdata> header.

@IssueDate 1..1 Load date of the notification.

@FormType 1..1 “NVR” for Notifications generated from a NINO Verification Request message. “NOT” for Notifications generated from a Full Payment Submission (FPS) or Employer Alignment Submission (EAS).

@SequenceNumber 1..1 Sequence number

CorrelationID 0..1 The CorrelationID allocated by the Transaction Engine to the incoming NVR, FPS or EAS message which instigated the Notification. This will allow the receiving software to associate the response with the request.

EmployerRef 1..1 The employer reference – composite of District number and reference.

Name 0..1 The parent element containing the name of the individual to whom the notification relates.

Name/Ttl 0..1 May optionally contain a title

Name/Fore 0..1 May optionally contain forename details

Name/Initials 0..1 May optionally contain initials

Name/Sur 1..1 Surname

NINOProvided 0..1 Will be populated with the NINO which was provided on the ‘incoming’ message, if any

PayId 0..1 For NVR messages this will contain the payroll ID included within the incoming NINO Verification Request. For NOT messages this will contain the payroll ID held by HMRC.

NINOToUse 0..1 Will be populated for messages 1, 3

MessageID 0..1 Denotes the action to be taken in order to deal with the relevant Notification correctly. The table below states the current allowable values.

v2.7 Page 5 of 12 13/11/2018

MessageID values and associated text

Message Scenario MessageID Static Text

FPS/EAS Substitute the NINO provided on FPS/EAS for this NINO

1 This notification shows the correct NINO. Please use this NINO for any future submissions instead of the one you originally provided.

NVR Substitute the NINO on the NVR for this NINO

FPS/EAS Stop using the NINO provided on FPS/EAS

2 There was no NINO provided or the one given is incorrect. Please do not use the incorrect one for any future submissions NVR NINO provided

on the NVR is incorrect and no NINO found

NVR No NINO provided on NVR and no NINO found

FPS/EAS Start using this NINO

3 For future submissions please use the NINO provided in this notification NVR NINO found

NVR The NINO provided is correct

4 The NINO you have provided is correct. For future submissions please continue to use this NINO.

NVR Service currently unavailable

5 Service currently unavailable

In the Production environment, ‘filing only’ agents are able to make submissions through the Transaction Engine for clients for whom they have not been authorised to act. Agents cannot download Notifications from the DPS if they are not authorised to act on behalf of the employer. This could mean that an Agent will not be able to download NINO Notifications from the DPS even if these were generated following submission of a NINO Verification Request message.

v2.7 Page 6 of 12 13/11/2018

7. Generic Notifications

Generic Notification Service (GNS) using GenericNotification-vN-N.xsd The generic notification message structure has been designed to support the following scenarios:

Notifications presenting information.

o E.g. Reminders, instructions, warnings, events

Notifications identifying data changes.

o E.g. Instructions to use different data item values, identifying updates to data item values. The schema supports these scenarios and the requirement to support simple presentation to users as well as providing identifiers that 3rd party applications can choose to use in order to implement more complex/automated processes with or without user intervention. The schema supports these scenarios with the following properties:

Relates to the employer reference and notifications may be at employer/contractor level or at a lower level, such as a specific appeal, or an individual employee.

May be in response to a correlating submission, or be unsolicited, or correlate to some other event.

Can optionally present any data item for information and/or change that can be mapped into a standard Key-Value pair structure and provides an extension point that can support more complex structures, if required in the future.

v2.7 Page 7 of 12 13/11/2018

7.1 – Generic Notification Structure

Element/Attribute Cardinality Description

GenericNotification 1..1 This is the root XML element containing the generic notification.

@IssueDate 1..1 Load date of the notification.

@FormType 1..1 This will be a hard coded enumeration of ‘GEN’.

@SequenceNumber 1..1 Notification sequence number used to control notification retrieval

MessageReference 1..1 A globally unique randomly generated reference number for the notification message. For internal HMRC use only, not for display purposes.

MessageTypeID 1..1 Each generic notification message type will contain a numeric identifier. Example messages are:

1 – Non filing notice

2 – Late filing notice

14 – CIS Penalty appeal accepted Each of the messages may include further data within the <Content> of the message. This will be included within an <Information> section identified by an appropriate namespace.

MessageTypeTitle 1..1 Human readable title of the notification. See “Content of key-value pair structure” below for example content.

MessageText 1..1 The message text provided by HMRC which should be displayed to the user. This may contain newline characters to denote a new paragraph. The newline character is intended to be represented by the ASCII 'LF' character (Hex value 0A):

Binary Oct Dec Hex

Abbreviation

[b]

[c]

[d]

Name (1967)

1963 1965 1967

000 1010

012 10 0A LF ␊ ^J \n

Line Feed

ASCII, https://en.wikipedia.org/w/index.php?title=ASCII&oldid=867731102 (last visited Nov. 13, 2018). The text of each message should not exceed 1500 characters.

DutyType 1..1 This will be ‘PAYE’ for all RTI Generic Notifications, or ‘CIS’ for CIS Generic Notifications

EmployerRef 1..1 The employer reference – composite of District number and reference.

EmployerName 1..1 The name of the employer or contractor.

Content 0..1 When included, will include content identified by namespace. May contain multiple items, but all items will be of the same type and namespace.

v2.7 Page 8 of 12 13/11/2018

7.2 – Information Structure

Element/Attribute Cardinality Description

Information 1..1 This is the root XML element for the Information schema that extends from the Generic Notification ‘Content’ element.

@seq 1..1 Integer sequence number to uniquely identify an iteration of this item.

InformationItem 1.. unbounded May contain one or more items which describe information related to this notification.

@id 1..1 ID of the data item number appearing within ‘Value’ See “Content of key-value pair structure” below for example content.

DisplayName 1..1 The display name is a human readable description of the ID attribute. See “Content of key-value pair structure” below for example content.

Value 1..1 The information value e.g. 2013-04-05

@Type 1..1 An attribute of ‘Value’ to define the type of value and format to assist software developers e.g. ‘Date’, ‘String’ etc. See “Content of key-value pair structure” below for example content.

Content of key-value pair structure Each generic message will contain human readable text within the <MessageText> element. In addition to this text, message-specific data can be contained within the <Information> section included within the <Content> of the message. Examples are given in the table below.

MessageTypeID MessageTypeTitle @id DisplayName Value @Type

1 Non filing notice 301 Period Ending YYYY-MM-DD xsd:date

2 Late filing notice 300 Date of Receipt YYYY-MM-DD xsd:date

14 CIS Penalty appeal accepted

305 306 307

Unique ID Default period ending Employer Accounts Office Reference

String YYYY-MM-DD String

xsd:String xsd:date xsd:String

Please note that this list is not exhaustive: additional notifications may be added in future releases.

v2.7 Page 9 of 12 13/11/2018

7.3 – Change Structure The Change Structure is reserved for future use.

Element/Attribute Cardinality Description

Change 1..1 This is the root XML element for the Change schema that extends from the Generic Notification ‘Content’ element.

@seq 1..1 Integer sequence number to uniquely identify an iteration of this item.

ActionItem 1.. unbounded May contain one or more items which describe changes related to this notification.

@id 1..1 ID of the data item number appearing within ‘Value’

DisplayName 1..1 A description of the data content within ‘Value’

PreviousValue 0..1 May optionally contain the previous information value e.g. 2012-09-07

@Type 1..1 An attribute of ‘PreviousValue’ to define the type of value and format to assist software developers e.g. ‘Date’, ‘String’ etc.

Value 1..1 The information value to be used e.g. 2012-09-14

@Type 1..1 An attribute of ‘Value’ to define the type of value and format to assist software developers e.g. ‘Date’, ‘String’ etc.

InformationItem 0.. unbounded May optionally contain one or more items which describe information related to this notification.

@id 1..1 ID of the data item number appearing within ‘Value’

DisplayName 1..1 A description of the data content within ‘Value’

Value 1..1 The information value e.g. 2012-09-14

@Type 1..1 An attribute of ‘Value’ to define the type of value and format to assist software developers e.g. ‘Date’, ‘String’ etc.

8. Outgoing XML Generator (OXG) This tool allows you to create additional test data in XML format; this can be used to supplement the static data available for retrieval from the DPS test service. The OXG contains a number of .csv files which are already populated with dummy data. We recommend that you replace this with more meaningful data. Do not rely on the existing data in these templates for testing purposes. Any amendments to the individual .csv files contained within OXG should be made in notepad or txt format and then re-saved as a .csv file. If amendments are made in .csv format you may receive format errors when using OXG to convert the file into XML format. Generic Notifications may contain newline characters in the MessageText to denote a new paragraph (see section 7.1 above). When using the OXG to create Generic Notifications for test purposes, such newline characters can be replicated by inserting {newline} where required in the appropriate ‘MessageText’ field in the example template.

v2.7 Page 10 of 12 13/11/2018

9. Test service All calls to the TPVS test service should be made using the URL endpoints described in section 2 within this document. The DPS test server holds a pre-defined set of test data in respect of P6, P6B, P9, SL1, SL2, PGL1, PGL2, Annual reminders, P35, P11D(b), RTI Notifications and Generic Notifications which will be stored in the test service. The test service requires you to include your existing PAYE or CIS test credentials (SenderID and Value) within the DPSrequestToken call (as Username and Password respectively). If you do not have credentials for use with the test service, please contact the Software Developer Support Team. In order to retrieve test data, the test service requires one of the following references in the <entity> element of your Soap call:

123/1739465, or

123/A6, or

123/AN64312 (not CIS), or

123/ZZYYXXWW (CIS only). To access all notifications in the test service, you will need to make retrievals for all these references. If you use references 848/I445 or 951/B7440 you will receive a response containing no forms. The test service has been set up as for an ‘agent’. Thus you can test retrieval of messages for multiple references if required. To do this, simply leave the <entity> element empty in your DPSretrieve call. If a request is made with a reference other than those listed, the test service will respond with an error indicating that the user does not have the rights to see data for that employer reference. You will have unrestricted access to the test service and testing can be managed according to your own cycles. All supporting documents required can be accessed at the DPS technical specifications page. RTI Notifications The NINO Verification Request message allows a user to request up to 100 NINOs to be verified within a single NVR message submitted through the Transaction Engine. The result of this NVR message will be made available for retrieval using DPS. In the live environment it is possible that not all of the NINOs included within a single submission will be matched within the same timeframe and therefore not all of the responses will be available for retrieval from DPS at the same time. It is not possible to replicate this behaviour within the test environment, as the test service contains static fictitious data which is not generated from data contained within an incoming submission. In the live environment there will be a genuine <CorrelationID> included within each NINO Notification to allow software to match it with the submitted NVR or FPS message which instigated the Notification. The test service data will contain fictitious entries within the <CorrelationID> element as these will not be generated from data contained within incoming submissions.

v2.7 Page 11 of 12 13/11/2018

Generic Notifications The test data for the GNS will include examples of generic wording within the <MessageText> element. This may not be an identical representation of the wording that will be issued to your customers but will include the examples of formatting in accordance with the live service.

10. Supplementary Guidance Content of SAML tokens The content of SAML tokens returned by the live service may look somewhat different to the content of the SAML tokens returned by the test service. However, since the SAML token is always regarded as an opaque ‘fragment’ of XML that is retrieved initially and then used unchanged in subsequent DPS calls, these differences should not affect the application code or the correct operation of the service. Please also note that there are some superficial differences between test and live service WSDLs relating to the exact strings used as namespace prefixes. The XML Namespace specification permits different name prefixes to be used in any particular XML document as long as the namespace ‘names’ to which the prefixes refer are identical. All element namespaces have been preserved between test and live services in both the WSDLs and any returned messages.

v2.7 Page 12 of 12 13/11/2018

Changes

Version number

Changes Date

2.0 Document renamed (Previously: How to use the DPS test service and gain internet recognition V1.7) Rewritten to include RTI data Vendor Recognition section removed to separate document Supplementary guidance incorporated Changes section added

24/06/2011

2.1 Section 2: removed references to endpoint URLs https://ws.hmrc.gov.uk/dpsauthentication/service and https://ws.hmrc.gov.uk/dps/service which are no longer supported Section 7: replaced “Message No” with “MessageID” to match schema

24/10/2011

2.2 Section 7: Scenario 5 wording amended 05/01/2012

2.3 Section 7: RTI Notifications sub-divided into 7.1 for NINO Notifications and 7.2 for Generic Notification Service. Explanatory table added at 7.1. Section 9: para 7 amended to clarify that the CorrelationID will also be returned for Notifications generated from EAS or FPS, as well as NVR.

31/10/2012

2.4 Sections 3, 4, 7, 8, 9: updated re Generic Notifications. Section 9: new paragraph on retrievals for multiple references Minor changes to grammar and formatting for clarity

26/09/2014

2.5 Amended for the introduction of Generic Notifications for the Construction Industry Scheme. Section 6 removed, subsequent sections renumbered. Some grammar corrections.

26/03/2015

2.6 References to Government Gateway changed to Transaction Engine. Minor amendments for clarity.

15/08/2017

2.7 Sections 3, 4, 9: amended for the introduction of Postgraduate Loan start and stop notices PGL1 and PGL2.

13/11/2018