Making Tax Digital at Crunch: a developer’s perspective

Making Tax Digital (MTD) is an HMRC initiative to completely transform how individuals and businesses manage their tax in the UK. This ambitious project aims to transform the tax system by providing APIs for software providers to integrate with. These APIs are designed to make the taxpayers’ experience of viewing and filing their returns much easier. The first APIs HMRC are providing are for viewing and filing VAT returns.

We’ve already created a blog post on what MTD means for VAT registered businesses which can be found here.

However, we thought it’d also be valuable to share our experiences about integrating with HMRC’s new APIs from a technical perspective.

What’s new?

When Spring Boot 2 came out, it seemed a reasonable choice to build our new microservices using the latest available version. We wanted to keep things as separate and as independent as possible, so we created a service specifically to deal with MTD VAT returns, and another one solely for the authorisation process. This doesn’t just make things more scalable, but makes the whole authorisation workflow reusable for other services also using an OAuth 2.0 flow.

As you’d expect, our VAT filing service needed to communicate with HMRC’s sandbox, which was quite a straightforward process since both services have been designed as REST APIs and both use JSON as the format of the payload.

There are five different endpoints introduced by HMRC, and we only had to interact with two of them to be eligible for a submission. One of these is to retrieve VAT obligations so we can double check that our record matches up with those held by HMRC. Every match found by our service gets a ‘period key’ from the response, which is mandatory before we can proceed.

After matching the return, we can use the other endpoint to submit a VAT return along the period key, which was provided in the first response.

There are further possible endpoints to use which are all optional, but they have great coverage on retrieving data such as View VAT Return, Retrieve VAT liabilities and Retrieve VAT payments.

So what about security?

So we mentioned that we’ve built two microservices. This is due to the fact that HMRC changed the way they deal with user-authentication and now they’ve given users much greater control when granting permissions. A user can grant access to an agent or even to a piece of software which can act on behalf of them when filing VAT returns. That includes specifying the exact permissions, such as read and write access for VAT.

In both cases, the access permissions a user grants expire after 18 months, but they also have the right to revoke the access at any given time using the government’s website.

So, thanks to the OAuth 2.0 workflow, the token provisioning process is quite straightforward. We have an HMRC agent account which holds the correct permissions for all our clients. Once our agent needs to log in to the HMRC website and grant permission to our software. This then generates an authorisation token which expires after 10 minutes. We have to send it back to HMRC within that time range and request an OAuth token alongside a refresh token which we can be stored on our side.

The OAuth token can be used to interact on behalf of the agent (and its related customers) for 4 hours. After that, we have to use the stored refresh token, which can be used to fetch a completely new pair of tokens, which we will have to store again.

Our thoughts on the new APIs

We really support HMRC for undertaking this forward-thinking project. We already integrate with many third-party RESTful APIs and we found the documentation and sandbox that HMRC provide to be very user-friendly. In particular, we see the following as the main benefits of the new APIs:

Real-time responses:

• One of the benefits is having a completely real-time response from HMRC, which immediately lets you know if a VAT return was successfully submitted, or was rejected for any reason. This is a huge step forward from the existing process which involves submitting a VAT return, and then polling at 20-minute intervals before we know whether the submission was successful or not.

Detailed error messages:

• Speaking of rejection, the new API won’t just return a simple error response, it now contains really detailed messages and descriptions of the origin of the error. That could be a business logic error, a missing period key, or even just an authorisation issue. We found these improvements really great, as ultimately these error messages will be read by accountants on a daily basis, and if they understand where the issue with the VAT return is, they don’t have to ask a developer to investigate issues by searching for log messages.

More control of data for users:

• Having these five endpoints gives companies a lot more flexibility to check and validate data before it’s actually sent for final submission. Unfortunately, the Sandbox environment created by HMRC doesn’t have all the functionality and has a lot of hard-coded responses, therefore these changes will only give real value when using them on the production system.

Summary

To summarise, we’re really excited by MTD bringing more online tax capabilities for small businesses. We believe the new APIs present a great opportunity for software providers to add even more value to customers and will empower innovation in Fintech companies.

Whilst MTD becomes mandatory for all VAT registered businesses from April 2019, there’s already a beta available which we’ve already used to successfully submit VAT returns for selected beta clients and we’re included in HMRC’s list of MTD compatible software providers.

Written by Chris Heisz and Conor Scott, Java Developers at Crunch. In Chris’ free time he enjoys writing books and composing pieces for symphonic orchestra whilst Conor enjoys learning Portuguese and reading Jo Nesbo books.

Find out more about the Technology team at Crunch and our current opportunities here.