Skip to content

Plan: HMRC connection (Making Tax Digital for VAT) ​

Status: plan, awaiting the Product Owner's approval (QD-23, QD-25, QD-26). Issue #85. No code yet.

Why ​

GetMy Books can't see HMRC. VAT return dates are calculated from each company's VAT quarters, so it can't tell whether a return was filed or paid, or what HMRC holds. Making Tax Digital (MTD) for VAT is the only MTD regime that applies to our limited companies today (#32), and HMRC's MTD VAT API is how software reads and files VAT with HMRC. This connection unlocks:

  • SPEC-001 S1: back-test each draft against the return HMRC holds.
  • SPEC-004: VAT dates from HMRC's obligations, plus "filed" and "paid", in place of calculated dates and "check it was done".
  • Later, SPEC-002 filing (write:vat) with approval on the web page (ADR 0005). Not part of this plan, but see "The catch".

The catch: production needs filing ​

HMRC's VAT (MTD) end-to-end service guide sets minimum functionality for production credentials (checked 2026-09-30):

  • send the fraud prevention headers the law requires;
  • retrieve VAT obligations;
  • submit a VAT return through the API.

Approval also needs HMRC to see accurate fraud prevention headers and a live submission, with the VRN, after sandbox testing. HMRC then takes about 10 working days (contact SDSTeam@hmrc.gov.uk; two questionnaires). The guide names no exception for read-only or in-house software.

So "read-only first" works in the sandbox, but production read access comes with filing, not before it. Options (QD-25):

  1. Ask HMRC first (recommended). Email the SDS team now: GetMy Books is in-house software for our own two companies, and wants read:vat only. Ask whether production credentials can be issued without submission, or what they need. It costs nothing, and the fraud prevention header Gov-Vendor-Product-Name already allows for "internal use only" software.
  2. Build filing and file one real return. Build SPEC-002 (approval on the web page, ADR 0005) in the sandbox, then file one real FEAW return through GetMy Books instead of Xero as the live submission. The first chance after the Jun–Aug 2026 return (due 7 Oct, filed by the accountant) is Sep–Nov 2026, due 7 Jan 2027. This needs Rob and the accountant to agree that GetMy Books files that quarter.
  3. Stay in the sandbox until one of those lands. Everything below is still built and tested; only the production switch waits.

Recommended: 1 now, with 3 in the meantime; 2 only if HMRC says no.

Stages ​

0. Paperwork (can start as soon as QD-23 is approved) ​

  • A Developer Hub account on an organisation address (dev@getmy.group or similar, not a personal one), with Rob and Fraser as team members.
  • A sandbox application subscribed to VAT (MTD) and Test Fraud Prevention Headers, and a sandbox test organisation from the Create Test User API.
  • Redirect URI: https://mcp.getmy.group/hmrc/callback (behind Access, the same login as /mcp). A second, http://localhost:3000/hmrc/callback, is for development only.
  • The email to the SDS team (option 1).

1. Connect a company (OAuth, per company) ​

  • A web page /hmrc/connect, behind Access and the per-person check, sends the person to HMRC's sign-in. They sign in with the Government Gateway user ID the company uses for VAT online (QD-26: who holds it for FEAW, Rob or the accountant). HMRC's page asks them to grant read:vat.
  • state is single-use, bound to the session and the entity, and expires in 10 minutes; HMRC's code also expires in 10 minutes.
  • The entity comes from the session only (rule 4). The VRN the token is used for is the entity's own, checked against HMRC's VAT customer information response, never taken from input.
  • Tokens are encrypted with encryptString (src/platform/crypto.ts) under a new key, HMRC_TOKEN_ENCRYPTION_KEY, and stored in hmrc_connection under RLS. Access tokens last 4 hours; refresh tokens stop after 18 months, when the company must reconnect.
  • The connect page is a person acting, so it sends the WEB_APP_VIA_SERVER fraud prevention headers, collected by the page's script (screen, window size, browser plugins, timezone, and so on) and forwarded by the server (ADR 0006).

2. The sync (fills the cache) ​

  • Once a day at 06:00 Europe/London, inside the deployed app, for each connected company. It's a batch with no person acting, so it sends BATCH_PROCESS_DIRECT headers, as HMRC's own example allows ("an overnight batch process to get VAT obligations"). These describe the NAS (the originating device): a stored device UUID, local IPs and MACs, timezone, OS, Gov-Vendor-Product-Name: GetMy Books, version.
  • It reads:
    • obligations (open and fulfilled, back 4 years);
    • submitted returns for each fulfilled period (nine boxes, HMRC keeps 4 years);
    • liabilities;
    • payments;
    • penalties, if the endpoint is enabled for the app.
  • Everything is converted to integer pence at the boundary (ADR 0025) and stored in vat_obligation, vat_return_filed, vat_liability and vat_payment, all under RLS with entity_id.
  • Failures: 401 → refresh once, then mark the connection broken and alert (the ntfy alert, docs/plans/alerting.md). 429 → honour Retry-After. 5xx or a timeout (30 seconds, timed-fetch) → keep the last good cache, and say how old it is.

3. Tools and features (read the cache, never HMRC) ​

ToolReturns
vat_obligationsOpen and recent periods: due date, received date, status (SPEC-001)
vat_hmrc_accountWhat HMRC says is owed and paid, per period, with the cache's age
vat_verify_return (existing)Compares a draft with the return HMRC holds, box by box (SPEC-001 S1)
deadlines_upcoming (existing)VAT dates from obligations; "filed" and "paid" from HMRC; "reconnect HMRC" 30 days before the 18 months end

No tool calls HMRC, submits or approves (rule 5, ADR 0006).

4. Production ​

Whichever option QD-25 chooses: fraud header evidence from the Test Fraud Prevention Headers API, the questionnaires, then production credentials in Doppler prd only (HMRC_CLIENT_ID, HMRC_CLIENT_SECRET), with the sandbox pair in dev. Each company connects once in production.

Acceptance tests ​

  1. Connect. Given a signed-in person with access to FEAW, when they complete /hmrc/connect with the sandbox test organisation, then an encrypted hmrc_connection row exists for FEAW only, and neither the token nor the code appears in any log.
  2. Forged callback. Given a callback with a state that is reused, expired, or from another session or entity, then it is refused and nothing is stored.
  3. Headers. Given the sync and the connect page, when their headers go to the Test Fraud Prevention Headers API, then HMRC reports no errors (warnings recorded and explained).
  4. Sync. Given the sandbox's canned obligations and returns, when the sync runs, then the cache holds them in pence and a second run changes nothing.
  5. Back-test. Given the filed Mar–May 2026 return in the cache, when vat_verify_return runs on FEAW's draft for that quarter, then each of the nine boxes matches (SPEC-001 S1).
  6. Expiry. Given a refresh token 18 months old, when the sync runs, then the connection is marked "reconnect needed", an alert goes out, and the deadline radar shows it.
  7. Isolation. Given a session for WealthTechPros only, then no FEAW HMRC data is returned.

Out of scope ​

  • Filing (SPEC-002), except as the route to production under QD-25 option 2.
  • MTD for Income Tax: sole traders and landlords, not limited companies; directors' own tax is post-MVP (CAP-02.6).
  • MTD for Corporation Tax: HMRC has set no date. PAYE: waits for QD-17 (b).
  • Agent access (the accountant's agent services account).

Decisions ​

RefDecisionRecommended
QD-23Start the Developer Hub application nowYes
QD-25Route to production credentialsAsk the SDS team first; sandbox meanwhile; file one real return only if HMRC requires it
QD-26Whose Government Gateway user ID authorises FEAW's connectionWhoever files FEAW's VAT online today (Rob or the accountant) to confirm
#32Making Tax DigitalClose as a watch item; this plan is the MTD VAT work

Sources ​