{"id":15610493,"url":"https://github.com/richpeck/vat-mtd","last_synced_at":"2025-04-28T12:06:23.321Z","repository":{"id":72453445,"uuid":"252420161","full_name":"richpeck/vat-mtd","owner":"richpeck","description":"VAT-MTD Integration for HMRC","archived":false,"fork":false,"pushed_at":"2022-02-17T20:34:45.000Z","size":1757,"stargazers_count":4,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-28T12:06:15.878Z","etag":null,"topics":["hrmc","mtd","ruby","sinatra","uk","vat"],"latest_commit_sha":null,"homepage":"https://vat-mtd.herokuapp.com","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/richpeck.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-02T10:07:54.000Z","updated_at":"2024-03-28T18:29:23.000Z","dependencies_parsed_at":"2023-04-13T09:33:24.217Z","dependency_job_id":null,"html_url":"https://github.com/richpeck/vat-mtd","commit_stats":{"total_commits":153,"total_committers":1,"mean_commits":153.0,"dds":0.0,"last_synced_commit":"3bf3ef5c0f79e45b5e5e6c6c69e988b5c89b326c"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richpeck%2Fvat-mtd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richpeck%2Fvat-mtd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richpeck%2Fvat-mtd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richpeck%2Fvat-mtd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/richpeck","download_url":"https://codeload.github.com/richpeck/vat-mtd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251311330,"owners_count":21569009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hrmc","mtd","ruby","sinatra","uk","vat"],"created_at":"2024-10-03T06:01:44.691Z","updated_at":"2025-04-28T12:06:23.301Z","avatar_url":"https://github.com/richpeck.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/downloads/richpeck/vat-mtd/total?style=flat-square\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/repo-size/richpeck/vat-mtd?logoColor=00FF00\u0026style=flat-square\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/languages/top/richpeck/vat-mtd?logoColor=00FF00\u0026style=flat-square\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/stars/richpeck/vat-mtd?style=flat-square\" /\u003e\n  \u003cbr /\u003e\u003cbr /\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/richpeck/vat-mtd?style=flat-square\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/issues-raw/richpeck/vat-mtd?style=flat-square\" /\u003e\n\u003c/div\u003e\n\u003cdiv align=\"center\"\u003e--\u003c/div\u003e\n\nRuby implementation of [HMRC's VAT (MTD) API](https://developer.service.hmrc.gov.uk/api-documentation/docs/api/service/vat-api/1.0).\n\nInspired by [100pcVATFreeBridge](http://www.comsci.co.uk/100PcVatFreeBridge.html), wanted to explore the technology required to facilitate such a solution.\n\n---\n\n# 🧠 Introduction\n\n[VAT (MTD)](https://www.gov.uk/government/publications/vat-notice-70022-making-tax-digital-for-vat/vat-notice-70022-making-tax-digital-for-vat) is an API endpoint of HMRC's [Making Tax Digital](https://en.wikipedia.org/wiki/Making_Tax_Digital) initiative.\n\nMTD was designed to streamline the tax system, allowing tax payers and developers to adopt solutions that boost efficiency and compliance.\n\nThe first step to realizing this has been to make VAT digital-only ([self assessment will become digital-only in 2024](https://www.sage.com/en-gb/blog/mtd-for-income-tax-sole-traders) for individuals earning over £10,000 p/a from self-employment). \n\n[Since April 2019](https://www.gov.uk/government/publications/vat-notice-70022-making-tax-digital-for-vat/vat-notice-70022-making-tax-digital-for-vat#example-1--existing-business-with-taxable-turnover-above-the-vat-registration-threshold-on-1-april-2019), VAT-registered buinesses have not been able to manually submit their VAT returns to HMRC and, instead, need to use a third party application to interface with the API.\n\nWhilst there are a number of \"done for you\" systems which do this (Xero, Sage etc), there remains people, such as myself, who prefer to keep their financial information private and use the likes of Spreadsheets track expenditure etc. \n\nFor this reason, \"[bridging software](https://www.gov.uk/guidance/find-software-thats-compatible-with-making-tax-digital-for-vat)\" was developed to connect to the likes of an Excel Spreadsheet and submit its data to HMRC. \n\nI originally began using [VitalTax](https://vitaltax.uk/), a plugin for Excel. This worked well for a time, and then became paid-only. Thus, I began looking around and found the [100pcVATFreeBridge](http://www.comsci.co.uk/100PcVatFreeBridge.html) software, which is effective and free.\n\nBecause of my background with API software development, I felt it would be a good exercise to create my own version of a VAT bridging package. I will detail what I've done in this regard below.\n\n---\n\n# 💻 Technical Scope\n\nThe VAT submission process is simple and has not changed with the digital transition.\n\nThere are [9 boxes](https://www.gov.uk/guidance/how-to-fill-in-and-submit-your-vat-return-vat-notice-70012#common-requirements-when-completing-boxes-1-to-9) on the VAT return form. These boxes are used to calculate the VAT owed (either by you or as a repayment by HMRC).\n\nVAT returns are submitted each quarter and there is little by way of regulation in terms of the veracity of data submitted. Whilst this has lead to fraudulent claims, it provides flexibility as regards to how your records are kept.\n\nIn my case, that's meant a continuation of the \"spreadsheet\" system I developed to track income and expenses for the business.\n\nThe most important part of this has been that I can control it, which means I can change/adapt/improve it over time. I don't want to have to pay for a system that gets access to all of my data and (crucially) locks you in without providing a means of escape.\n\nI think it's healthy to provide the means for people to create solutions that encourage transarency and efficiency. The old, opaque, systems provided by HMRC were shrouded in mystery and constantly caused confusion \u0026 issues. By opening up their API's to the public, the flows of data to HMRC will become much more robust and efficient, permitting developers (such as myself) to create solutions around them.\n\n---\n\n# 📒 Submission Process\n\nTo submit a VAT return, a VAT-registered business is required to present HMRC with a 9-box form at the end of each quarter.\n\nThe structure of these forms is well documented so I won't cover them here.\n\nI will, however, explain how the new VAT-MTD API endpoints work with them, and what that means for the development of software solutions.\n\n--\n\nHMRC's \"Making Tax Digital\" system is - at its heart - a series of [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) [API endpoints](https://developer.service.hmrc.gov.uk/api-documentation/docs/api/service/vat-api/1.0).\n\nBecause these endpoints are standardized, it means that we're able to create software which interact with them.\n\nWhilst the software may vary, the pattern remains the same - an HTTP request is made to HMRC's servers with a payload of data. HMRC's application then computes the data, storing it on their system and providing a response to our application.\n\nThe endpoints are protected with the [oAuth standard](https://developer.service.hmrc.gov.uk/api-documentation/docs/authorisation), which makes interfacing with them relatively simple.\n\nOnce authenticated with a user's account, your software should be able to submit and manage their VAT returns using the above URLs.\n\n---\n\n# 💾 Software\n\nMy implementation is coded in [Ruby](https://www.ruby-lang.org/en/) and utilizes the [Sinatra](http://sinatrarb.com/) web framework.\n\nDue to its web-based nature, it is multi-tenant. This means there are two layers of authentication - creating a user account on my app and then connecting with HMRC via oAuth.\n\nThe system's flow is modelled after the 100pcVATFreeBridge product above - inside the user area, you can see a list of VAT returns (both past and present), upload a spreadsheet and allocate data to different boxes of a VAT return.\n\nWhenever a new VAT return is made available, you are able to send the spreadsheet data through the API and receive a response.\n\nTo highlight how this works from a code standpoint, I will detail the different elements below: -\n\n\u003cp\u003e-\u003c/p\u003e\n\n## 1️⃣ Sinatra\n\nSinatra is the basis of the application, as it provides an interface between [Rack](https://en.wikipedia.org/wiki/Rack_(web_server_interface)) and Ruby.\n\nIt allows us to create a web based experience without having to load Rails, making it efficient and robust.\n\nThe entrypoint for a Sinatra app is the `config.ru` file, which, in the case of my app, loads another file called [`./config/autoload.rb`](https://github.com/richpeck/vat-mtd/blob/master/config/autoload.rb).\n\nThis calls a number of Sinatra extensions, which aren't overly important. The most important is the interface with [ActiveRecord](https://github.com/sinatra-activerecord/sinatra-activerecord), which allows us to build database-driven applications utilizing [ActiveRecord](https://github.com/rails/rails/tree/main/activerecord) from the Rails core team.\n\n\u003cp\u003e-\u003c/p\u003e\n\n## 2️⃣ oAuth\n\nThe oAuth system is necessary to connect to HMRC and interact with user accounts.\n\nI have implemented my own version of this, which you can see [here](https://github.com/richpeck/vat-mtd/blob/master/lib/omniauth/strategies/hmrc_vat.rb).\n\nAs the authentication with HMRC is handled with oAuth, we are able to take advantage of the various oAuth gems to create a reliable and efficient system.\n\nI'll come back and explain this stuff more specifically when I get the app fully functioning.\n\n\u003cp\u003e-\u003c/p\u003e\n\n## 3️⃣ HMRC\n\nA requirement to have an application registered with HMRC is present.\n\nOnce this is in place, you are able to accept inbound oAuth requests, ultimately allowing users to grant permission to interface with their HMRC account.\n\nAs with the oAuth policy, I will explain this more specifically when it's polished.\n\n\u003cp\u003e-\u003c/p\u003e\n\n## 4️⃣ Submit\n\nFinally, to submit the VAT returns, we are simply creating an API payload for the appropriate VAT return.\n\nI'll detail this another time.\n\n---\n\n# ✔️ Contributions\n\nYou are welcome to contribute as you wish: -\n\n- Fork the repo and clone it locally\n- Make the changes you want/need\n- Commit your local repo and push to your remote repository\n- Create a PR to bring the new changes into our master branch\n- Anyone is welcome to contribute whatever they wish.\n\nPlease be aware that we are not responsible for any product/solution which uses the code from this repository. \n\n---\n\n##### ⚖️ Copyrights/Licenses\n\nCopyrights owned by respective contributors.\n\nThis is open source software, distributed under the [MIT license](/richpeck/vat-mtd/blob/master/LICENSE). Provided \"as-is\" with no warranty.\n\n---\n\n©️ \u003ca href=\"http://www.frontlineutilities.co.uk\" title=\"Frontline Utilities LTD\"\u003e\u003cimg src=\"https://i.imgur.com/xwejn02.jpg\" align=\"absmiddle\" /\u003e\u003c/a\u003e \u003ca href=\"https://www.github.com/richpeck\" title=\"Richard Peck\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/1104431?v=3\u0026s=460\" height=\"22\" align=\"absmiddle\" /\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frichpeck%2Fvat-mtd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frichpeck%2Fvat-mtd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frichpeck%2Fvat-mtd/lists"}