Making Tax Digital (MTD) VAT Submission Platform
Direct HMRC API integration for MTD VAT return submission, removing manual spreadsheet bridging software
Background
HMRC's Making Tax Digital mandate requires VAT-registered businesses to submit returns digitally via compatible software. The client needed a platform that handled the HMRC OAuth2 flow and VAT return API without relying on third-party bridging software, which typically means a spreadsheet plug-in bolted onto a workflow that was never designed around it.
What We Built
A NestJS API handling the full HMRC MTD integration: OAuth2 authorisation code flow, token exchange and refresh, VAT obligation retrieval, and VAT return submission. An encryption service handles secure credential storage. A Next.js frontend guides users through the HMRC authorisation flow and return preparation. Key schemas:
- User
- account with HMRC credentials stored encrypted
- VAT Return
- submission records with HMRC receipt acknowledgement
- Token
- OAuth2 token storage with expiry and refresh metadata
- Admin User
- internal admin access for accountant oversight
Architecture
NestJS with a dedicated HMRC module containing controller, service, and module for clean separation. An encryption module wraps all sensitive field operations. MongoDB handles persistence. Next.js powers the client-facing submission UI.
Results
VAT returns bridged through third-party spreadsheet software
Direct HMRC OAuth2 integration for submission, refresh, and receipts
Credential handling written inline with business logic
Encryption isolated into its own auditable, independently rotatable module
Outcomes & Lessons Learned
- Direct HMRC API integration for MTD VAT return submission, removing manual spreadsheet bridging software
- OAuth2 token lifecycle management with encrypted storage and automatic refresh
- VAT return history with submission receipts stored per user account
- Encryption service isolating sensitive credential handling from business logic
HMRC's MTD API has strict rate limiting and token validation requirements. Building the encryption service as a standalone NestJS module, rather than inline in the HMRC service, meant credentials handling could be audited, tested, and rotated independently of the API logic.
Questions, answered.
The things people ask us about this project. If yours isn't here, ask us directly, we reply like humans.
Ask us anything→How does the platform authenticate with HMRC?
Through HMRC's OAuth2 authorisation code flow, with token exchange, refresh, and encrypted storage handled by a dedicated encryption module rather than inline in the HMRC integration code.
What happens to VAT submission receipts?
Submission records are stored with HMRC's receipt acknowledgement per user account, so there's a retrievable history of every return and its confirmation.
Why was credential encryption built as its own module instead of inline?
So credentials handling could be audited, tested, and rotated independently of the HMRC API logic, which matters given HMRC's strict rate limiting and token validation requirements.
Does this replace third-party bridging software?
Yes, the platform integrates directly with HMRC's MTD API for VAT return submission, removing the need for spreadsheet-based bridging software that typically bolts onto a workflow it wasn't designed around.
What does the HMRC integration actually cover?
OAuth2 authorisation, token exchange and refresh, VAT obligation retrieval, and VAT return submission, all contained in a dedicated HMRC module with its own controller, service, and module for clean separation.
Ready to craft tomorrow, today?
Where innovation meets execution, and ideas evolve into impactful solutions. Book a free consultation, no strings attached.