Walkthrough: Integrate 'HMRC DPS' in a tenant application ⚓︎

This guide will walk you through the steps required to integrate with HMRC DPS to retrieve tax codes for your investors.

Overview ⚓︎

This guide covers the following topics:

  1. Setting up HMRC DPS in the sandbox environment
  2. Setting up HMRC DPS in the production environment

1. Setting up HMRC DPS in the sandbox environment ⚓︎

1 - Log into the system with your credentials and go to Configurations sections and select Integrations option from Home page.

2 - Select HMRC tab and select DPS. Then you will be shown a modal with DPS configurations.

3 - In order to configure DPS from the WealthOS backend, you need to obtain two fields from the HMRC console - ((i) Gateway User Id, (ii) Password) and submit to the WealthOS backend via this window.

4 - To obtain a Gateway User Id and a Password you must first register for HMRC sandbox testing. Then you should go to the (https://developer.service.hmrc.gov.uk/api-test-user) create a test user with the type as organisation. The Gateway User ID and Password should resemble the format shown below.

5 - For the "Vendor ID" and "Employee Ref," please use the values "1111" and "123/1739465" respectively. Then test the connection to ensure it is successful.

6 - Once the test connection is successful, select the index number dropdown. Choose the "I'm registered with HMRC and I know the Index of the last tax code update" option from the dropdown menu, and provide the last retrieved index, as "4012". Save this DPS configuration.

7 - Now your WealthOS account has HMRC DPS to get investor tax codes.

8 - To continue testing you must create one or more investors with below tax codes.

  • RN000011C - RN000001A
  • RN000012D - RN000006B
  • RN000013A - RN000005A
  • RN000014B - RN000004D
  • RN000015C - RN000003C

2. Setting up HMRC DPS in the production environment ⚓︎

1 - Follow steps 1 and 2 from the Sandbox Environment setup.

2 - Provide your Gateway User ID and the Password used during HMRC registration. Also, fill in the Vendor ID and Employee Ref with the allocated SDST vendor ID and the Employee Ref.

3 - Once the test connection is successful, select the index number dropdown.

  • If you are newly registered with HMRC, select the "Newly registered with HMRC, no tax code history applicable" option from the dropdown menu.
  • If you know the last index you retrieved (this will be the HighWaterMark from your last DPSretrieve request), select the "I'm registered with HMRC and I know the Index of the last tax code update" option from the dropdown menu and provide the last retrieved index.
  • If you do not know the last index you retrieved, select the "I'm registered with HMRC and I don't know the Index of last tax code update" option from the dropdown menu and provide the last date you synced up with HMRC to get the tax codes. Then click the Fetch button. This will automatically retrieve the last index you received up until the date you provided.

4 - Then save the DPS configuration.

5 - You are now ready to use HMRC DPS in your production environment.