/finance-expert

Reconciliation and close

Reconciliation is the control that converts a belief into a fact. Your ledger says you hold 1,204,331.18 EUR of customer money; the bank says something else; the PSP says a third thing. Exactly one of those is the money. Reconciliation finds, explains, owns and closes every difference between what you recorded and what the world recorded (M9); the close freezes a period once every difference is explained (M10). Engineers under-build both because they look like batch jobs. They are controls — with named owners, an evidence trail an auditor will read (M14), a separation-of-duties requirement (M11), and an SLA measured in aged money. The matching code is maybe 20% of the work.

1. What reconciliation is, and what it is not

Three-way reconciliation — internal ledger ↔ processor/settlement report ↔ bank statement — is the baseline for any business that takes card money. Two-way is not enough: ledger↔PSP proves you booked what the processor processed and says nothing about whether the money landed; PSP↔bank proves the payout arrived and says nothing about whether your books know. All three legs, always, because breaks live in the leg you skipped. The same machinery reconciles anything where two records must agree:

What reconciliation is not. Comparing totals: SUM(ours) == SUM(theirs) is a smoke test, not a control — two offsetting errors of 4,000 net to zero, and a total match with 340 unmatched items is a failed reconciliation reporting green. Reconciliation is item-level: every line on each side is either matched to a specific line on the other side, or it is a break with an owner. A dashboard: a "match rate" chart nobody must act on is telemetry; a reconciliation produces a signed statement plus a list of exceptions with owners. A reason to edit history: corrections are reversing entries and new entries (M3). Optional for internal money: wallet balances, points and credits are liabilities; they reconcile to a control account or they drift.

The rule. Your database is never the authority for money that moved. For money that moved on a rail you do not operate, the authority is the rail's record. Your ledger is the authority for your accounting of it — a different claim. When they disagree you do not "fix the data"; you book the difference to a break account and investigate (M9, M16).

Completeness before accuracy. Most teams build amount comparison first. Wrong order: the dangerous break is the item on neither side because you never ingested it — the failed download, the day with no statement, the currency you don't handle. Assert completeness first: sequence continuity, opening balance = prior closing balance, header control totals, expected file count per day per account.

2. Sources and their formats

Cross-cutting traps, each of which has caused a restatement somewhere:

3. Ingestion discipline

Ingestion is where reconciliation becomes trustworthy or does not. Four rules.

1. Idempotent file ingestion (M7). A file's natural idempotency key is the SHA-256 of its bytes plus the source and declared statement identity. Re-ingesting identical bytes is a no-op returning the original ingestion id. Re-ingesting different bytes under the same statement identity is a restatement — an event, not an overwrite.

2. Immutable raw storage (M3, M14). Persist the original bytes to object storage before parsing, with retrieval metadata (source, account, fetched-at, path, hash, size, credential identity — never the credential, M15). Every downstream row references the raw object, so "show me the bank statement supporting this line" produces the original file, not your parse of it.

3. Parse then normalise, as separate stages. Parsing yields source-shaped records with the source's own field names and raw strings; normalisation maps them to the canonical external-line model with typed amounts (M4), tz-aware timestamps, classified line types and extracted references. Separate, so a normalisation fix re-runs over stored parses without re-fetching and a parser change is diffable against golden files.

4. Detect gaps and drift, loudly, at ingest rather than at close.

-- Ingestion tables. Append-only; nothing here is ever UPDATEd or DELETEd (M3).
CREATE TABLE recon_source_file (
    id              BIGSERIAL PRIMARY KEY,
    source_code     TEXT NOT NULL,                -- 'ADYEN_SETTLEMENT', 'BANK_DE_CAMT053'
    account_ref     TEXT NOT NULL,                -- IBAN, merchant account, PSP account
    content_sha256  BYTEA NOT NULL,
    object_uri      TEXT NOT NULL,                -- immutable blob location
    stmt_identity   TEXT,                         -- camt <Stmt><Id>, MT940 :28C:, report id
    stmt_seq_no     BIGINT,                       -- legal/electronic sequence number
    coverage_from   TIMESTAMPTZ NOT NULL, coverage_to TIMESTAMPTZ NOT NULL,
    currency        CHAR(3) NOT NULL,
    opening_balance NUMERIC(38,8), closing_balance NUMERIC(38,8),
    declared_count  INTEGER, declared_sum NUMERIC(38,8),   -- control totals from the header
    supersedes_id   BIGINT REFERENCES recon_source_file(id),   -- restatement chain
    superseded_by   BIGINT REFERENCES recon_source_file(id),
    parser_version  TEXT NOT NULL,
    status          TEXT NOT NULL,                -- INGESTED | QUARANTINED | SUPERSEDED
    ingested_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
    UNIQUE (source_code, account_ref, content_sha256)
);
-- Exactly one live version per declared statement identity.
CREATE UNIQUE INDEX recon_stmt_identity_live ON recon_source_file
    (source_code, account_ref, stmt_identity)
    WHERE stmt_identity IS NOT NULL AND superseded_by IS NULL;

CREATE TABLE recon_external_line (
    id           BIGSERIAL PRIMARY KEY,
    file_id      BIGINT NOT NULL REFERENCES recon_source_file(id), line_no INTEGER NOT NULL,
    external_id  TEXT,                            -- NtryRef, balance_transaction_id
    line_type    TEXT NOT NULL,                   -- CHARGE|REFUND|FEE|PAYOUT|DISPUTE|ADJ|UNKNOWN
    amount_minor BIGINT NOT NULL, currency CHAR(3) NOT NULL,      -- signed minor units (M4)
    txn_amount_minor BIGINT, txn_currency CHAR(3),-- original currency when settlement differs (M6)
    booking_date DATE NOT NULL, value_date DATE,  -- booking date in the source's own timezone
    event_time   TIMESTAMPTZ,                     -- when it happened, if the source says (M10)
    counterparty TEXT,
    refs         JSONB NOT NULL DEFAULT '{}',     -- extracted candidate references
    raw          JSONB NOT NULL,                  -- the parsed source record, verbatim
    UNIQUE (file_id, line_no)
);
CREATE INDEX ON recon_external_line (currency, booking_date, amount_minor);   -- blocking key
CREATE INDEX ON recon_external_line USING GIN (refs jsonb_path_ops);

Continuity checks, each of which pages someone on failure:

Schema drift detection is a hard fail with quarantine, not a warning. Fingerprint each file structurally (sorted column names for CSV, sorted XPaths for XML, record type codes for fixed-width) and compare against the registered fingerprint for that source+parser version. Unrecognised structure → store the file, mark the ingestion QUARANTINED, normalise nothing, let a human decide. A parser that silently ignores an unknown column will silently ignore a new fee type, and you find out in the P&L.

Restatement handling. When a source re-issues a corrected file, never overwrite: insert a new recon_source_file with supersedes_id set, normalise its lines, re-run matching for the affected window. The old version's lines are marked superseded, not deleted; matches referencing them are invalidated and re-proposed; ledger postings already made from them are corrected by reversal (M3). Keep both versions forever — "why did the number change between Tuesday and Wednesday" only has a factual answer if you did.

4. The matching engine

4.1 The reference-propagation problem

Matching is trivial when both sides carry the same identifier and impossible when they do not. The engineering work is upstream: get your identifier into the rail's reference field and make sure it comes back.

Design rules: the reference is an opaque, collision-free, checksummed id you generated (not a customer name, not a reusable invoice number); uppercase alphanumeric only, because intermediaries mangle punctuation and case; it fits the narrowest field on the path; it is stored on the internal record before you instruct the rail (M7 — the same key that makes the instruction idempotent); and you assume it will sometimes be absent, truncated to 16 characters, or wrapped in the counterparty's own text, so you match on checksum-validated extraction rather than equality alone. For inbound money you do not control, you propagate the reference by publishing it (invoice, payment instructions, portal) and accept that 5–20% of humans will not use it — hence the heuristic passes.

4.2 Pass architecture

Matching is an ordered pipeline of passes, strongest evidence first. Each pass consumes only still-unmatched items; each match records the pass, the rule and the evidence (M14). Never run heuristics before deterministic passes: a fuzzy pass that consumes an item a later exact rule would have matched is a data-corruption bug wearing the costume of a break.

Auto-match thresholds are policy: declared in configuration, versioned, owned by finance — not constants in code. A rule that auto-matches at 0.60 books wrong money quietly.

4.3 Cardinality

1:1 is the ideal — one charge, one statement line. 1:N / N:1 — a payout batching many charges, a bank credit covering ten invoices — is modelled as a group: a match holds a set of internal lines and a set of external lines and must satisfy Σ internal = Σ external per currency, with any deliberate difference (fees, spread) an explicit member of the group rather than a residual you tolerate away (M16). N:M — net settlement, where a PSP nets charges, refunds, fees, chargebacks and reserve movements into one payout — is never solved by free-form search: that is combinatorially hopeless and manufactures coincidental matches. Use the provider's own grouping (the payout id on each balance transaction) to build the group deterministically, then verify the arithmetic. If the provider gives no grouping, reconcile at aggregate level with a documented reconciling-items statement rather than pretending you matched line by line.

4.4 Tolerance

A tolerance is legitimate only when it corresponds to a known physical cause with a bounded magnitude, and the difference is booked somewhere (M5, M16):

A tolerance is a bug in disguise when the delta has no explanation you can compute from the fee schedule or the rate; when it is always the same sign (you are systematically losing or gaining); when it scales with volume (a percentage error, not a rounding error); or when it had to be widened to make yesterday's run go green. Widening a tolerance needs the same approval as a write-off, because that is what it is — an automated write-off with no ceiling. Record tolerance consumption in money, per rule, per day, and alert on the trend: a tolerance eating 40 EUR/day eats 14,600 EUR/year.

4.5 Explainability and storage

Store why, not just that: the pass, rule id, rule version, the evidence (which fields matched, with which values), the confidence, the tolerance consumed, and who confirmed it. Six months later an auditor asks how you know a particular 220,000 EUR credit belongs to a particular payout batch; "the algorithm matched it" is not an answer.

CREATE TABLE recon_match (
    id              BIGSERIAL PRIMARY KEY,
    run_id          BIGINT NOT NULL REFERENCES recon_run(id),
    rule_id         TEXT NOT NULL, rule_version TEXT NOT NULL, pass_no SMALLINT NOT NULL,
    confidence      NUMERIC(4,3) NOT NULL,
    mode            TEXT NOT NULL,             -- AUTO | PROPOSED | CONFIRMED | REJECTED
    evidence        JSONB NOT NULL,            -- {"on":["ref","amount"],"reference":"PMT7QK…"}
    tolerance_minor BIGINT NOT NULL DEFAULT 0, tolerance_ccy CHAR(3),
    decided_by      TEXT,                      -- NULL for AUTO; never an automation identity (M11)
    decided_at      TIMESTAMPTZ, created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE recon_match_member (
    match_id BIGINT NOT NULL REFERENCES recon_match(id),
    side     TEXT   NOT NULL,                  -- INTERNAL | EXTERNAL
    line_id  BIGINT NOT NULL,
    PRIMARY KEY (match_id, side, line_id)
);
-- One live match per line; unmatching writes a new row, it never edits one (M3).
CREATE UNIQUE INDEX ON recon_match_member (side, line_id)
    WHERE match_id IN (SELECT id FROM recon_match WHERE mode IN ('AUTO','CONFIRMED'));

4.6 Performance at scale

At 10M lines a day, O(n²) candidate generation is not a slow implementation, it is the wrong algorithm. Blocking keys: a few hash keys per line ((currency, amount_minor), (currency, amount_minor, booking_date), (normalised_ref), (counterparty_hash, amount_minor)); candidates are only lines sharing a block; join in the database or in one hashed in-memory pass, never nested loops over the day. Incremental windows: a run covers [T−lag, T] where lag is the longest rail settlement delay plus margin (ACH returns 60 days; disputes reconcile on their own cycle, not the daily cash one), matched lines excluded by index rather than scan, plus a separate "aged unmatched" pool that every run re-attempts so a 40-day-old item still matches today without re-scanning 40 days. Deterministic, idempotent runs: a run is keyed by its inputs — the file versions it saw and the rule-set version — which is what makes replaying a fixed matcher over history possible at all (§14).

4.7 Reference implementation sketch

"""Matching engine core. Python 3.11+. Integer minor units only (M4); no floats anywhere."""
from __future__ import annotations
from collections.abc import Iterable, Iterator, Sequence
from dataclasses import dataclass, field
from datetime import date, timedelta
from typing import Literal, Protocol

Side = Literal["INTERNAL", "EXTERNAL"]

@dataclass(frozen=True, slots=True)
class Line:
    line_id: int; side: Side
    amount_minor: int                        # signed minor units
    currency: str                            # ISO 4217 (M4, M6)
    booking_date: date
    refs: frozenset[str] = frozenset()       # normalised candidate references

@dataclass(frozen=True, slots=True)
class Match:
    rule_id: str; rule_version: str; pass_no: int
    internal: tuple[int, ...]; external: tuple[int, ...]   # groups, so 1:N is native
    confidence: float
    evidence: dict[str, object]              # why, not merely that (§4.5)
    tolerance_minor: int = 0

class Rule(Protocol):                        # every pass implements exactly this
    rule_id: str; rule_version: str; confidence: float; auto: bool
    def propose(self, pool: "Pool") -> Iterator[Match]: ...

class Pool:
    """Unmatched lines plus blocking indexes; a consumed line is never revisited."""
    def __init__(self, lines: Iterable[Line]) -> None:
        self._lines = {l.line_id: l for l in lines}; self._consumed: set[int] = set()

    def alive(self, side: Side) -> list[Line]:
        return [l for l in self._lines.values()
                if l.side == side and l.line_id not in self._consumed]

    def block(self, side: Side) -> dict[tuple[str, int], list[Line]]:
        idx: dict[tuple[str, int], list[Line]] = {}      # the blocking key of §4.6
        for l in self.alive(side): idx.setdefault((l.currency, l.amount_minor), []).append(l)
        return idx

    def consume(self, m: Match) -> bool:
        ids = set(m.internal) | set(m.external)
        if ids & self._consumed: return False            # a stronger pass already took a member
        self._consumed |= ids
        return True

class ReferenceRule:
    """Pass 2: propagated reference equality. Ambiguity is a break, not a coin flip."""
    rule_id, rule_version, confidence, auto = "REF_EXACT", "3", 1.0, True

    def propose(self, pool: Pool) -> Iterator[Match]:
        by_ref: dict[str, list[Line]] = {}
        for l in pool.alive("EXTERNAL"):
            for r in l.refs: by_ref.setdefault(r, []).append(l)
        for ours in pool.alive("INTERNAL"):
            cands = {c.line_id: c for r in ours.refs for c in by_ref.get(r, [])}
            if len(cands) != 1: continue
            theirs = next(iter(cands.values()))
            if theirs.currency != ours.currency: continue           # M6, never net across ccy
            if theirs.amount_minor != ours.amount_minor: continue   # amount delta → break
            yield Match(self.rule_id, self.rule_version, 2,
                        (ours.line_id,), (theirs.line_id,), self.confidence,
                        {"on": ["reference", "amount", "currency"],
                         "reference": sorted(ours.refs & theirs.refs)})

@dataclass(slots=True)
class AmountWindowRule:
    """Pass 5: amount+currency inside a date window, only when unique on BOTH sides."""
    window_days: int = 3
    rule_id: str = "AMT_WINDOW"; rule_version: str = "2"
    confidence: float = 0.90; auto: bool = True

    def propose(self, pool: Pool) -> Iterator[Match]:
        blocks, hits, staged = pool.block("EXTERNAL"), {}, []
        for ours in pool.alive("INTERNAL"):
            lo = ours.booking_date - timedelta(days=self.window_days)
            hi = ours.booking_date + timedelta(days=self.window_days)
            cands = [t for t in blocks.get((ours.currency, ours.amount_minor), [])
                     if lo <= t.booking_date <= hi]
            if len(cands) != 1: continue                  # ambiguity → leave it for a human
            hits[cands[0].line_id] = hits.get(cands[0].line_id, 0) + 1
            staged.append(Match(self.rule_id, self.rule_version, 5,
                                (ours.line_id,), (cands[0].line_id,), self.confidence,
                                {"on": ["amount", "currency", "date_window"],
                                 "day_delta": (cands[0].booking_date - ours.booking_date).days}))
        yield from (m for m in staged if hits[m.external[0]] == 1)   # unique the other way too

# Pass 3 (N:1) has the same shape: take the provider's own grouping {payout_line: [our_lines]},
# refuse it unless the members share one currency (M6) and Σ members == −payout exactly, then
# yield one Match whose `internal` tuple is the whole group. A residual is a break, never a plug.

@dataclass(slots=True)
class RunResult:
    matches: list[Match] = field(default_factory=list)
    proposals: list[Match] = field(default_factory=list)     # need a human (M11)
    unmatched: list[Line] = field(default_factory=list)      # become break objects (§6)

def run_passes(lines: Sequence[Line], rules: Sequence[Rule],
               auto_threshold: float = 0.90) -> RunResult:
    """Ordered passes, strongest evidence first. Deterministic: no wall clock, stable order."""
    pool, out = Pool(lines), RunResult()
    for rule in rules:
        for m in list(rule.propose(pool)):               # materialise before consuming
            if not (rule.auto and m.confidence >= auto_threshold):
                out.proposals.append(m)
            elif pool.consume(m):
                out.matches.append(m)
    out.unmatched = pool.alive("INTERNAL") + pool.alive("EXTERNAL")
    return out

Nothing in proposals or unmatched may be silently dropped, and nothing posts to the ledger without the confirmation step: automation proposes, a person approves (M11).

5. Break taxonomy

Classify every break — an unclassified break is an unowned break, and unowned breaks age into write-offs. The correcting entry is always a new entry or a reversal, never an edit (M3).

Two rules finance insists on and engineers resist. The correcting entry is never a plug to the principal account — you do not "adjust revenue" to make cash agree, you find the account the difference belongs to (M16). And breaks are booked, not merely tracked: a break past the materiality threshold that has not been posted to a break or suspense account is a real difference sitting outside the books, so the trial balance is describing a world you already know is wrong.

6. Break management as an operational object

A break is a first-class record with a lifecycle (M9, M14), not a row in someone's spreadsheet.

CREATE TABLE recon_break (
    id               BIGSERIAL PRIMARY KEY, run_id BIGINT NOT NULL,
    reconciliation   TEXT NOT NULL,     -- 'BANK_DE', 'PSP_ADYEN', 'SUBLEDGER_GL_CASH'
    break_type       TEXT NOT NULL,     -- taxonomy in §5
    side             TEXT NOT NULL,     -- INTERNAL | EXTERNAL | BOTH
    amount_minor     BIGINT NOT NULL, currency CHAR(3) NOT NULL,
    detected_on      DATE NOT NULL,
    source_event_date DATE,             -- the date the underlying item claims (M10)
    owner            TEXT NOT NULL,     -- a named person or rota, never 'system'
    status           TEXT NOT NULL,     -- OPEN|INVESTIGATING|PENDING_EXTERNAL|RESOLVED|WRITTEN_OFF
    materiality      TEXT NOT NULL,     -- LOW | MEDIUM | HIGH | REPORTABLE
    resolution_entry BIGINT,            -- the journal entry that closed it (M3)
    root_cause       TEXT, closed_at TIMESTAMPTZ, closed_by TEXT,
    CONSTRAINT closed_needs_evidence CHECK (status NOT IN ('RESOLVED','WRITTEN_OFF')
      OR (resolution_entry IS NOT NULL AND closed_by IS NOT NULL AND root_cause IS NOT NULL))
);
CREATE INDEX ON recon_break (status, reconciliation, currency, detected_on);

The aging report is the operational artifact, produced daily rather than at close. Report gross exposure (Σ|amount|): netting is how a +50,000 and a −50,000 break become a clean report while a customer is missing 50,000.

SELECT reconciliation, currency,
       width_bucket(CURRENT_DATE - detected_on, ARRAY[3,8,31,91]) AS bucket, -- 0-2/3-7/8-30/31-90/90+
       count(*)                        AS n,
       sum(abs(amount_minor))          AS gross_exposure_minor,
       max(CURRENT_DATE - detected_on) AS oldest_days,
       percentile_cont(0.95) WITHIN GROUP (ORDER BY CURRENT_DATE - detected_on) AS age_p95
FROM recon_break WHERE status NOT IN ('RESOLVED','WRITTEN_OFF')
GROUP BY 1,2,3 ORDER BY 1,2,3;

Materiality is set by finance, per reconciliation, in absolute currency and as a percentage of the account balance, and it drives investigation depth, never whether the break exists. A 3 EUR break is still a break; it may be batch-resolved to the rounding account under a standing written policy that caps total batch-resolved value per period.

Write-offs book a real loss or gain, so: the investigator proposes and a named approver at the right threshold approves — automation may propose, never approve (M11); thresholds are tiered (say <100 team lead, <5,000 finance manager, <50,000 controller, above that CFO), declared in configuration and enforced by the system rather than by convention (M12); the entry carries the break id in its narrative and posts to a designated write-off account, never buried in revenue or cost (M16); and write-off volume is a reported metric — growth means the reconciliation is failing and the write-off is concealing it.

A growing suspense account is an incident. A suspense/clearing account holds value in transit for a short declared period; its balance should oscillate around zero and clear within the rail's settlement window. Monotonic growth means you are systematically receiving or paying money you cannot explain. Alert on absolute balance, on the count of items older than the clearing SLA, and on growth over N consecutive days, and treat it with the severity of an availability incident — it is a correctness incident with a regulator attached. Clearing-account design is in ledger.md.

7. Controls and evidence

Reconciliation is a control, and a control that leaves no evidence did not happen.

The sign-off artifact. At the end of each reconciliation period, generate an immutable document and store it, hashed, with the run: reconciliation name and period; opening and closing balance per side; reconciling items with amounts and ages; matched value and count; unmatched gross value and count; breaks created, resolved and written off; the journal entries produced; preparer, reviewer and both timestamps. This is the first artifact an auditor asks for, and generating it from the system rather than assembling it from screenshots is the difference between a clean audit and a sampling exercise.

The control matrix an auditor will request, per reconciliation: control id and description ("CASH-01: daily three-way reconciliation of EUR acquiring"); frequency; named owner and reviewer; population and completeness evidence (which sources, which files, sequence proof); materiality and tolerance thresholds in force with their approval reference; evidence produced (sign-off artifact id, run id, break list); exceptions in the period with count, value and resolution status; and which steps are system-enforced rather than manual — because those steps are ITGC-dependent.

SOX ITGC applies to the systems producing the numbers, not only to the numbers. Where the reconciliation is automated, the auditor tests general controls over the automating system: change management (who deploys a matching-rule change, with what review), logical access (who can post journals or alter tolerances, with evidence of periodic review), and operations (scheduling, failure detection, backup/restore, evidence a failed run was noticed and re-run). A perfect matching engine behind a main branch anyone can push to is a control deficiency regardless of correctness. Regimes and evidence in compliance-regulatory.md; deployment and access mechanics in architecture-ops.md.

8. Cutoff and periods

Three times, always distinguished (M10):

The cutoff rule, precisely. An entry belongs to period P if its event time, converted to the entity's accounting timezone, falls within P's boundaries, and P is open at booking time. If P is closed, the entry posts to the earliest open period with an explicit reference to the original event date and an out-of-period flag. Booking time never determines the period. That paragraph, written down and enforced in code, prevents most cutoff arguments.

Timezone policy for a global business. Declare, per legal entity, the accounting timezone (usually the entity's local zone; some groups standardise the sub-ledger on UTC and translate at consolidation). Store every timestamp tz-aware in UTC plus its originating zone and derive the period by explicit conversion, never a naive date cast — a 23:55 UTC transaction in a UTC−8 entity is the previous day, and date(created_at) gets a slice of every day's volume wrong. Sources emitting dates with no time or zone (most bank statements) get a per-source declaration that their booking date is the period-determining field; record that decision instead of inferring it.

Late-arriving items are normal: a settlement file after cutoff, a fee reported a week late, a chargeback for a Q1 charge landing in Q3.

Nothing posts to a closed period, ever (M10). Enforce it in the ledger, not the application: a period status table, a check constraint or trigger on posting, and separate authorization to reopen a soft-closed period as a logged, approved event rather than a config flag. If the ledger accepts a backdated posting, someone will make one at 23:00 on the last day of the audit.

Soft close vs hard close. Soft close (D+2 to D+3) freezes the sub-ledgers and produces provisional management numbers with a declared basis (M20) — good enough to run the business, marked provisional. Hard close (D+5 to D+8) completes accruals, reconciliations, FX revaluation, intercompany and review, then locks. Publishing a soft-close number without the "provisional" label is how a board deck ends up contradicting the statutory accounts.

Subsequent events. Between period end and issue of the accounts, information arrives. An event giving evidence about a condition that existed at period end is adjusting — a customer becoming insolvent the following week, confirming a receivable was already impaired; a chargeback confirming a provision was insufficient. An event about a new condition is non-adjusting: disclosed, not booked. Engineers matter here because the data feed's cutoff decides what evidence finance ever sees — if disputes are ingested weekly, adjusting information is invisible until it is too late.

9. The close

9.1 Close calendar (D0 = last calendar day of the period)

Compress this calendar by pushing work earlier — continuous daily reconciliation, accruals computed daily, revenue recognised on a rolling basis — never by skipping steps. A five-day close is a consequence of clean daily reconciliation, not of working faster in the last week.

9.2 Checklist by area

9.3 Journal entries: automated vs manual

Manual journal entries are the highest-risk object in the close — they bypass every business rule in the sub-ledger. Instrument them: count and value per period per preparer, which accounts they hit, how many touch revenue or cash, how many are prepared and approved inside one team. A rising manual JE count is the leading indicator that a feed broke and people are compensating by hand. Never let an automation identity approve one (M11).

Close blockers. Keep an explicit list, refreshed daily during close: what is blocking, which step, who owns it, target time. A blocker is a missing file, an unreconciled account, an unapproved JE, an unresolved material break or a system failure. That list is the close's critical path; without it, the close finishes when someone feels finished.

9.4 Metrics

10. Accruals and deferrals

The pattern: at period end, book what economically belongs to the period but has not yet flowed through the normal transaction path; on day 1 of the next period, reverse the accrual, so the real item posts normally when it arrives without double counting. Automatic reversal is what makes accruals safe — a non-reversing accrual plus the actual invoice is a doubled expense, the most common close error there is.

Prepaid/deferred cost is the mirror: cash out now, expense later — Dr Prepaid expenses / Cr Cash at payment, then Dr Expense / Cr Prepaid expenses monthly on a schedule. Both accruals and prepaids must be calculated from data (open POs, contract terms, dispute cohorts) and generated by the system from reviewed inputs, never typed from last month's file with the number changed.

11. Revenue recognition (IFRS 15 / ASC 606)

The standards are converged enough that the five-step model is the same. Engineers build the machinery; the policy belongs to the finance owner and the auditor (SKILL.md §11 — a recognition treatment is not decided in a code review).

The output is a recognition schedule per performance obligation — contract, PO, amount, currency, start, end, method (straight-line by day, by usage, on delivery, on milestone), recognised to date. Everything else — deferred revenue, the waterfall, ARR and its bridges (corporate-finance.md) — derives from it plus the ledger (M1, M19).

11.1 The four business shapes

11.2 Worked example and postings

A SaaS contract: 12,000 EUR annual prepaid on 2026-04-01 covering 2026-04-01 → 2027-03-31, plus a 2,000 EUR onboarding fee. Finance has determined onboarding is not distinct, so the 14,000 EUR transaction price is one performance obligation over 365 days. Daily rate 14,000.00 ÷ 365 = 38.356164…, recognised to the cent at the declared rounding mode, residual to the final period so the schedule sums exactly to 14,000.00 (M5).

Never let the residue drift: assert Σ schedule = transaction price, exactly, per contract, in a test (M5, M18). If that customer cancels on 2026-09-30 with a contractual 3,000.00 refund, the remaining liability splits — Dr Contract liability 3,000.00 / Cr Refund payable 3,000.00 for the obligation to return cash, and Dr Contract liability (remainder) / Cr Revenue (remainder) for the portion earned. Refunds reduce revenue (a reversal of the transaction price), never an expense; a refund sitting in cost of goods sold overstates revenue permanently. Service-failure credits are also revenue reductions (variable consideration) while marketing credits may be an expense — encode the distinction in the credit type, do not leave it to whoever books it.

11.3 The revenue waterfall / rollforward

The rollforward proves the deferred balance and the revenue line come from the same system (M19), and must tie exactly every period: opening contract liability + new billings deferred − revenue recognised − refunds and credits released ± contract modifications = closing contract liability, equal to the GL account balance, per currency.

There is no FX term, and adding one is the error. A contract liability is non-monetary, so it is not retranslated (§12): within a single currency there is nothing to revalue, and a non-zero FX line in this rollforward means something is revaluing a balance it must leave at its historical rate. Translating the closing balance into the presentation currency for consolidation is a separate, later step — average rate for the revenue line, closing rate for the balance sheet, difference to CTA in OCI (§12) — and it belongs to the consolidation pack, not to this rollforward.

-- Rollforward from the recognition sub-ledger, tied to the GL (M19), per currency (M6).
-- No FX_REVAL movement kind exists: a contract liability is non-monetary and is not retranslated (§12).
WITH m AS (SELECT currency,
       sum(amount_minor) FILTER (WHERE kind='DEFERRAL')     AS deferred,
       sum(amount_minor) FILTER (WHERE kind='RECOGNITION')  AS recognised,
       sum(amount_minor) FILTER (WHERE kind='REFUND')       AS refunded,
       sum(amount_minor) FILTER (WHERE kind='MODIFICATION') AS modified
    FROM rev_schedule_movement WHERE period='2026-09' GROUP BY currency)
SELECT o.currency, o.balance_minor AS opening, m.*, g.balance_minor AS gl_closing,
       o.balance_minor + m.deferred - m.recognised - m.refunded + m.modified
         - g.balance_minor AS difference       -- must be 0, or the close is blocked (M2, M6)
FROM rev_balance_opening o JOIN m USING (currency)
JOIN gl_account_balance g ON g.account='2400-CONTRACT-LIABILITY'
                         AND g.currency=o.currency AND g.period='2026-09';

11.4 Contract modifications

A subscription "upgrade" is therefore not an UPDATE on a row. It is a contract event with an effective date, a new schedule and a reallocation. Model contracts as versioned with effective-dated amendments, or the schedule cannot be rebuilt and nobody can see what was promised when.

11.5 Principal vs agent — the decisive marketplace question

You are the principal (revenue gross, the underlying as cost of revenue) if you control the good or service before it transfers to the customer. Indicators of control:

The effect is enormous, and it is the number most often disputed in diligence or an IPO. A marketplace with 100M GMV and a 15% take rate reports 100M revenue / 85M cost of revenue / 15% gross margin as principal, or 15M revenue / no cost of revenue / 100% gross margin as agent. Same cash, same profit, a 6.7× difference in the top line. Postings for one 100.00 EUR order with a 15.00 EUR take rate and a 2.50 EUR PSP fee:

# AGENT (net) — the seller's share never touches revenue
Dr Cash                    100.00
    Cr Payable to seller             85.00   # liability, not revenue
    Cr Commission revenue            15.00
Dr Payment processing fees   2.50
    Cr Cash                           2.50   # fees are their own postings (M16)

# PRINCIPAL (gross) — same cash, different top line
Dr Cash                    100.00
    Cr Revenue                      100.00
Dr Cost of revenue          85.00
    Cr Payable to supplier           85.00
Dr Payment processing fees   2.50
    Cr Cash                           2.50

Two engineering obligations follow. The seller payable is a liability from the moment you collect — never revenue, never "cash we happen to hold", and in many jurisdictions it is safeguarded client money with its own regulatory treatment (SKILL.md §11, compliance-regulatory.md). And build both views from the same postings: keep gross transaction value, take rate, seller share and each fee in separate accounts (M16), so a change in the principal/agent conclusion is a presentation mapping change rather than a data migration. Teams that book only the net figure cannot produce a gross view later without re-deriving it from operational tables, which contradicts M19.

12. FX at close

Every entity has a functional currency; balances and transactions in other currencies are translated, and the rule differs by item type (M6 — every conversion is a recorded event with rate, source and timestamp).

Realised vs unrealised. Unrealised FX comes from revaluing an open monetary balance at the closing rate; realised FX comes from settling at a rate different from the booking rate. Both usually hit the same P&L line but must stay separately identifiable — treasury needs to know how much of that line is economic settlement and how much is a mark that will unwind. A 100,000 USD receivable booked at 0.9200 and closing at 0.9350, functional currency EUR:

booked 100,000 × 0.9200 = 92,000.00 EUR;   closing 100,000 × 0.9350 = 93,500.00 EUR
Dr Accounts receivable (FX revaluation)   1,500.00 EUR
    Cr Unrealised FX gain                          1,500.00 EUR

Settling at 0.9310 gives a realised gain of 1,100.00 EUR against the original booking, of which 1,500.00 was already recognised — so settlement books a 400.00 EUR loss unwinding part of the mark. That only works if the revaluation is stored per balance with its rate and date, not as a lump adjustment to an account total.

Engineering rules. Rates come from a declared source with a declared timestamp convention (which fixing, which time, which side of the spread), are stored immutably, and the rate used is recorded on the posting (M6). Revaluation is a generated, reversible entry — reversing it on day 1 of the next period and re-revaluing keeps the arithmetic simple and makes the realised/unrealised split mechanical. Never revalue a non-monetary balance because it happens to sit in a foreign-currency sub-ledger: classify accounts monetary/non-monetary in the chart of accounts (ledger.md) so revaluation is driven by data rather than by an annual argument.

13. GL export and ERP integration

The sub-ledger keeps the detail; the GL takes summaries (M19). A GL with 30 million lines a month is unusable, unauditable in practice and expensive in every ERP that prices by transaction. The rule: summarise into the GL, retain the detail in the sub-ledger, and make every GL line drillable back to the postings that composed it — an auditor sampling one GL line must reach the underlying items in one query.

Journal batch format — the batch is the unit of idempotency and of rejection: batch_id (deterministic, from source system + period + account set + run — this is the idempotency key, M7); period (must be open in the ERP); entity; posting_date and event_date, both (M10); lines[] each carrying account, dimensions (cost centre, product, region), debit or credit, amount in minor units and currency (M4) and a narrative, balancing per currency (M2, M6); source_reference, the sub-ledger summary id that enables drill-back; hash, for change detection and evidence; and reversal_of for reversing accruals.

Account mapping is a versioned artifact. The table from (sub-ledger event type, product, currency, entity) → (GL account, dimensions) lives in version control with a review requirement and an effective date; it is not a table someone edits in production. Changing a mapping mid-period splits the period's postings across two accounts and is a close blocker if undeclared. Validate every mapping against the ERP's live chart of accounts at batch build time, so a batch referencing a closed or non-existent account fails before it is submitted.

Keep a posting register: one row per attempted batch with its hash, external id, submission time, response, ERP document number and status. It is your idempotency store, your evidence, and your answer to "did that journal actually land?" — a question you will be asked at 22:00 on D+4.

14. Building the reconciliation system

Architecture. Stages, each independently replayable, each writing immutable output:

fetch ─→ ingest ─→ parse ─→ normalise ─→ match ─→ break ─→ post ─→ sign-off
  │        │         │          │          │        │        └ GL export (§13)
  │        │         │          │          │        └ break lifecycle (§6)
  │        │         │          │          └ match + evidence (§4.5)
  │        │         │          └ canonical external_line
  │        │         └ source-shaped records, versioned parser
  │        └ raw bytes, hashed; file registry; sequence and balance-chain checks (§3)
  └ scheduled against an expected-file calendar, with fetch-failure alerts

Testing (M18).

Use recorded real files, never hand-written ones. Every source has quirks nobody documents — the weekend file with a zero-line statement, the fee row with a negative amount and a positive sign field, the reference the bank pads with spaces — and only real files carry them. Keep them in the repo, scrubbed, with the scrubbing itself tested.

Observability (M17). Alert on the control failing, not on job duration:

Dashboards are for humans investigating; alerts are for the control failing. The final check that the whole machine works is a scheduled job that recomputes the trial balance from raw postings and compares it with the reported balances (M1, M2, M17). If that ever disagrees, nothing downstream — no reconciliation, no close, no report — can be trusted until it is explained.

Review questions

1. For each account that holds money, name the external record that is authoritative for it, the reconciliation frequency, and the named owner of its breaks. Which accounts have no answer?
2. Show me an item that matched. What evidence is stored for why it matched, which rule and rule version produced it, and who — if anyone — confirmed it?
3. What happens when a settlement file is redelivered with different content under the same statement identity? Trace the effect on postings already made from the superseded version.
4. What is the total tolerance consumed per rule over the last 90 days, in money? Which account is it booked to, and who approved the tolerance being that wide?
5. Take the oldest open break: how old, how much, whose, what classification, and what correcting entry will close it? If it is over 90 days, why is it still open?
6. Is your suspense/clearing balance oscillating around zero or trending up? Show the last 90 days.
7. An event occurred at 23:58 local time on the last day of the period, in an entity whose accounting timezone is not UTC, and was booked three days later. Which period does it land in, and what in the code enforces that?
8. Try to post a journal entry into a closed period. What stops you — the application, or the ledger? Who can reopen a period, and where is that logged?
9. For your largest revenue stream: what are the performance obligations, what is the recognition method, and does the deferred revenue rollforward tie exactly to the GL account this period?
10. If the marketplace principal-vs-agent conclusion flipped tomorrow, is that a presentation mapping change or a data migration? What in the posting model decides the answer?