Skip to content

0013: Bank reconciliation from the bank, not the browser ​

Status note: the live-source parts (Starling token, aggregator) are superseded by ADR 0035 (2026-10-08); statement files are the only source.

Context ​

The owner wants the Starling business account reconciled in Xero with as little manual work as possible. Investigated 2026-09-28:

  • Xero's Accounting API has no endpoint for bank statement lines and cannot reconcile. Xero's own MCP server has no such tool either.
  • The Finance API's Bank Statements Plus endpoint returns statement lines but needs the finance.bankstatementsplus.read scope, which Xero grants only to approved lending partners.
  • IsReconciled: true on a created payment, bank transaction or transfer marks that record reconciled but does not match the feed line. The feed line stays open, and the next reconcile creates a duplicate.
  • Driving the Xero web app from a browser breaches the Xero Developer Platform Terms, clause 29 ("bots or browser automation"; "simulates user actions without Xero's explicit authorisation"). Clause 31 allows immediate suspension of the app, which would cut off every GetMy Books feature for both companies.
  • Xero's own automatic bank reconciliation (JAX, beta) can clear statement lines. It is included on the Comprehensive plan but needs the accountant's agreement to switch on.
  • Starling offers read-only personal access tokens for business accounts. Their feed carries the same transactions Xero's bank feed receives, with amounts in minor units.

Decision ​

  1. Read the bank statement directly from Starling, read-only, with a per-entity token stored encrypted like the Xero token. Never from environment variables.
  2. Reconciliation logic is pure code in src/rules/, in integer pence. It compares Starling's statement with Xero's records, lists what is unreconciled and why, and checks the totals tie.
  3. The OK that clears a statement line stays in Xero, pressed by the owner, or by Xero's automatic reconciliation if it is switched on. GetMy Books never automates the Xero web app.
  4. The first slice is read-only against Xero. Creating the missing Xero records is a later slice. It needs approval outside chat, as in 0005, because bank references are free text any payer controls and must never drive a ledger write through a language model.
  5. If automatic reconciliation is switched on, the same tool checks its work (coding and VAT tax types) rather than trusting it.

Consequences ​

  • New scope: a bank connection (Starling only) and a reconciliation check. docs/not-doing.md narrows "Bookkeeping" and records browser automation as refused.
  • src/starling/ is a new integration module. It never imports src/xero/ or src/hmrc/.
  • The Xero app needs read access to bank transactions and bank transfers, and a reconnect for each entity.
  • A test asserts no MCP tool in this slice writes to Xero.
  • If Xero later publishes a reconcile or statement-line API, revisit point 3.