Appearance
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.readscope, which Xero grants only to approved lending partners. IsReconciled: trueon 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
- Read the bank statement directly from Starling, read-only, with a per-entity token stored encrypted like the Xero token. Never from environment variables.
- 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. - 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.
- 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.
- 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.mdnarrows "Bookkeeping" and records browser automation as refused. src/starling/is a new integration module. It never importssrc/xero/orsrc/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.