Appearance
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):
- Ask HMRC first (recommended). Email the SDS team now: GetMy Books is in-house software for our own two companies, and wants
read:vatonly. Ask whether production credentials can be issued without submission, or what they need. It costs nothing, and the fraud prevention headerGov-Vendor-Product-Namealready allows for "internal use only" software. - 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.
- 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.groupor 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 grantread:vat. stateis 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 informationresponse, never taken from input. - Tokens are encrypted with
encryptString(src/platform/crypto.ts) under a new key,HMRC_TOKEN_ENCRYPTION_KEY, and stored inhmrc_connectionunder 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_SERVERfraud 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_DIRECTheaders, 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_liabilityandvat_payment, all under RLS withentity_id. - Failures: 401 → refresh once, then mark the connection broken and alert (the ntfy alert,
docs/plans/alerting.md). 429 → honourRetry-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)
| Tool | Returns |
|---|---|
vat_obligations | Open and recent periods: due date, received date, status (SPEC-001) |
vat_hmrc_account | What 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
- Connect. Given a signed-in person with access to FEAW, when they complete
/hmrc/connectwith the sandbox test organisation, then an encryptedhmrc_connectionrow exists for FEAW only, and neither the token nor the code appears in any log. - Forged callback. Given a callback with a
statethat is reused, expired, or from another session or entity, then it is refused and nothing is stored. - 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).
- 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.
- Back-test. Given the filed Mar–May 2026 return in the cache, when
vat_verify_returnruns on FEAW's draft for that quarter, then each of the nine boxes matches (SPEC-001 S1). - 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.
- 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
| Ref | Decision | Recommended |
|---|---|---|
| QD-23 | Start the Developer Hub application now | Yes |
| QD-25 | Route to production credentials | Ask the SDS team first; sandbox meanwhile; file one real return only if HMRC requires it |
| QD-26 | Whose Government Gateway user ID authorises FEAW's connection | Whoever files FEAW's VAT online today (Rob or the accountant) to confirm |
| #32 | Making Tax Digital | Close as a watch item; this plan is the MTD VAT work |
Sources
- HMRC, VAT (MTD) end-to-end service guide (minimum functionality, production approval): https://developer.service.hmrc.gov.uk/guides/vat-mtd-end-to-end-service-guide/
- HMRC, User-restricted endpoints (4-hour access tokens, 18-month refresh tokens): https://developer.service.hmrc.gov.uk/api-documentation/docs/authorisation/user-restricted-endpoints
- HMRC, Fraud prevention, connection methods and
BATCH_PROCESS_DIRECT: https://developer.service.hmrc.gov.uk/guides/fraud-prevention/connection-method/ - HMRC, VAT (MTD) API 1.0: https://developer.service.hmrc.gov.uk/api-documentation/docs/api/service/vat-api/1.0