GovTech API Integration — HMRC Making Tax Digital for Accountancy SaaS

HMRC OAuth 2.0 Agent Authorisation: HMRC MTD uses a three-way OAuth 2.0 flow: the accountant (agent) authorises on behalf of their client (principal). ClickMasters implemented the Agent Authorisation API, Authorisation Code flow with PKCE, token refresh, and the HMRC sandbox environment for development and testing. Agent-client relationships persisted in PostgreSQL with full audit logging. MTD VAT Submission Flow: Obligation retrieval (HMRC API returns VAT return periods), VAT return calculation (pulling from client bookkeeping data), 9-box VAT return JSON construction (per HMRC schema), submission with fraud prevention headers (mandatory IP address, device ID, username headers — non-negotiable for HMRC), and confirmation receipt storage. HMRC Fraud Prevention Headers: HMRC mandates fraud prevention headers on all MTD API calls — including user IP address, browser fingerprint, and device identification. ClickMasters implemented these headers correctly with client-side collection (JavaScript) and server-side forwarding. Common compliance failure: missing or malformed fraud prevention headers cause HMRC to reject API calls. MTD ITSA Preparation: Pre-built the MTD Income Tax Self Assessment (ITSA) integration structure (from April 2026 mandatory date) — quarterly submission endpoints, digital record-keeping requirements, and the expanded self-employment income categories. Building this concurrently with VAT integration reduced future development cost.