How an accountant uses AccountantUK to file to HMRC

The five-step loop from connecting your Agent Services Account to a SHA-256 hashed, immutable receipt in the audit log. Below the narrative there's an honest breakdown of which returns we submit directly and which we hand back as a ready-to-upload artefact.

1. Step 1 — One-time setup

   The HMRC handshake

   Inside the accountant portal, click Connect to HMRC. We run the UK Government OAuth flow against your firm's master Agent Services Account (ASA) credentials. The returned authorisation token is encrypted at rest with AES-256-GCM (see lib/secrets.ts) before it ever touches the database. From that point on the software has legal API access to file for any client that has authorised your firm — no client passwords, no shared Gateway logins.

2. Step 2 — Doing the work

   Act as the client

   From your master client list, find the client and click Act-As. We set a server-signed cookie (ACT_AS_MAX_AGE_SEC = 4 hours) and your screen becomes the client's dashboard. Review the AI-scanned receipts, check the ledgers, let the tax module compute the figures. You never see the client's password and never need a 2FA code. Every page load you make in act-as mode is recorded in the audit log against your real identity.

3. Step 3 — Legal sign-off

   Send for client approval

   UK law: you can't push the final Submit button without explicit written approval from the client. Click Send for Approval and the figures land in the Quarterly Reviews module (status DRAFT). The client gets an alert on their phone, opens the app, reviews the math, taps Approve. The record transitions to APPROVED, audit-logged with the client's identity and timestamp. Days of email chase replaced by a tap.

4. Step 4 — The submission

   Direct API submission

   Once the review is APPROVED, you click Submit to HMRC on a green-badged module (VAT, ITSA quarterly, ITSA crystallise, RTI FPS, CIS300). The backend compiles the MTD REST payload or GovTalk XML envelope, attaches the HMRC fraud-prevention headers (Gov-Client-* device + IP + timezone, computed by lib/hmrc-fraud-headers.ts), and fires the call using your master ASA token. Amber-badged modules (CT600, SA800, CGT, SDLT, P11D) stop one step earlier — we generate the iXBRL or computation file for you to upload to the relevant HMRC / Companies House portal yourself.

   Files directly to HMRC: VAT · ITSA · RTI FPS · CIS300Compute & export — you file: CT600 · SA800 · CGT · SDLT · P11D

5. Step 5 — Forensic defensibility

   Immutable receipt + audit log

   HMRC replies with a Correlation ID. We render the receipt PDF (e.g. lib/vat-receipt-pdf.ts for VAT), hash it with SHA-256, and write the bytes + hash to private Vercel Blob storage. The action is appended to the audit log (lib/audit.ts — append-only by design). If HMRC ever investigates the client years later, the accountant has forensic proof of exactly what was filed, when, by whom, and that the client signed off first.