recskit 0.1.0__tar.gz

recskit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duckboard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

recskit-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: recskit
+Version: 0.1.0
+Summary: Reconcile a supplier or customer statement against your accounting ledger: match invoices, credit notes, and payments, flag mismatches and missing items, compare balances. No dependencies in the core -- works with any data source.
+Author: Duckboard
+License: MIT
+Project-URL: Homepage, https://github.com/Duckboard/recskit
+Project-URL: Buy me a coffee, https://ko-fi.com/duckboard
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: sage
+Requires-Dist: sagekit>=0.1.0; extra == "sage"
+Provides-Extra: parse-pdf
+Requires-Dist: pdfplumber>=0.10; extra == "parse-pdf"
+Requires-Dist: anthropic>=0.30; extra == "parse-pdf"
+Dynamic: license-file
+
+# recskit
+
+Reconcile a supplier or customer statement against your own accounting
+ledger: match invoices, credit notes, and payments; flag mismatches
+and missing items on either side; compare balances. The core has
+**zero dependencies** and doesn't care where your data came from --
+CSV, a PDF you parsed by hand, Sage, Xero, QuickBooks, anything.
+
+If this saves you time, consider [buying me a coffee](https://ko-fi.com/duckboard).
+
+## What problem this solves
+
+Checking a supplier statement against your own ledger by eye is slow
+and error-prone, especially once an account has more than a handful of
+open items. Two things make it worse than it looks:
+
+1. **A tied-up total balance doesn't mean every line is right.** Two
+   errors can cancel out -- a mismatched invoice and a missing one can
+   add up to the same total as if nothing were wrong. recskit checks
+   every line, not just the bottom-line figure.
+2. **Reference matching is a trap.** A short reference like `991` can
+   turn up as a *substring* of an unrelated, older invoice's reference
+   (`INV-99910`) on a long-standing account. Match on substring first
+   and you'll silently pair the statement line with the wrong invoice,
+   reporting a confident-looking "mismatch" instead of correctly
+   reporting no match at all. recskit always tries an **exact**
+   reference match before ever falling back to substring matching.
+
+## Features
+
+- Matches invoices/credit notes by reference (with support for
+  statements that print two references for the same line), payments
+  by amount first then reference
+- Exact-match-first, substring-fallback matching order -- see above
+- Configurable payment-terms due-date calculation (flat N days,
+  N days from the start of the following month, N days from end of
+  month, or end of the following month with no offset)
+- Flags items in your ledger that never show up on the statement at
+  all (commonly an old item sitting in a brought-forward balance)
+- Zero required dependencies in the core -- add the optional `sage`
+  extra only if you want the bundled Sage 50 adapter
+- Two worked examples: pure CSV (no external system at all), and Sage
+  50 via [sagekit](https://github.com/Duckboard/sagekit)
+
+## Installation
+
+```bash
+pip install -r requirements.txt      # core only, zero dependencies
+pip install -e .                     # or, as an editable package
+pip install -e ".[sage]"             # + the optional Sage 50 adapter
+```
+
+## Usage
+
+```python
+from recskit import StatementItem, LedgerInvoice, LedgerPayment, reconcile_statement
+
+items = [
+    StatementItem(type="invoice", ref="INV-100", amount=500.00),
+    StatementItem(type="invoice", ref="INV-101", amount=320.00),
+    StatementItem(type="payment", ref="bacs", amount=300.00),
+]
+
+ledger_invoices = [
+    LedgerInvoice(ref="INV-100", amount=500.00, outstanding=500.00),
+    LedgerInvoice(ref="INV-101", amount=300.00, outstanding=300.00),
+]
+ledger_payments = [LedgerPayment(ref="BACS-9001", amount=300.00)]
+
+result = reconcile_statement(items, ledger_invoices, ledger_payments, statement_balance=800.00)
+
+print(result.agreed, result.issue_count, result.balance_difference)
+for r in result.mismatched_items + result.missing_items:
+    print(r.item.ref, r.status, r.note)
+```
+
+### Payment-terms due dates
+
+```python
+from datetime import date
+from recskit import calc_due_date
+
+calc_due_date(date(2026, 5, 14), 30)                                   # 30 days from invoice date
+calc_due_date(date(2026, 5, 14), 29, "start_of_following_month")       # 29 days from 1 June
+calc_due_date(date(2026, 5, 3), 14, "end_of_month")                    # 14 days from 31 May
+calc_due_date(date(2026, 5, 3), 0, "end_of_following_month")           # 30 June, terms_days ignored
+```
+
+### Examples
+
+```bash
+python examples/reconcile_csv.py                         # runs on the bundled sample CSVs
+python examples/reconcile_csv.py statement.csv ledger.csv 1063.45   # your own files
+python examples/reconcile_sage.py                         # requires the "sage" extra + a live Sage 50
+```
+
+`reconcile_csv.py` needs no external system at all -- a good starting
+point for wiring recskit up to whatever export your own accounting
+software produces. `reconcile_sage.py` shows the same reconciliation
+against a live Sage 50 purchase ledger account, using
+`recskit.sage_adapter` to fetch the ledger side and
+[sagekit](https://github.com/Duckboard/sagekit) for the ODBC
+connection and column auto-detection.
+
+### Concept reference
+
+| Concept | Meaning |
+|---|---|
+| `StatementItem` | One line from the statement you're checking (invoice, credit note, or payment) |
+| `LedgerInvoice` / `LedgerPayment` | The equivalent transaction as it exists in your own ledger |
+| `MatchResult.status` | `"ok"`, `"mismatch"` (found but wrong amount), or `"missing"` (no match at all) |
+| `extra_in_ledger` | Ledger invoices never referenced by any statement line -- check these aren't being missed, or are simply old brought-forward items |
+| `balance_difference` | `ledger_balance - statement_balance` |
+
+## Bring your own data source
+
+The reconciliation logic never touches a database, file, or network --
+you build `StatementItem` / `LedgerInvoice` / `LedgerPayment` lists
+however suits your setup, and call `reconcile_statement()`. Options:
+
+- Parse a PDF or CSV statement export yourself (see
+  `examples/reconcile_csv.py`)
+- Pull the ledger side from Sage 50 with `recskit.sage_adapter` (see
+  `examples/reconcile_sage.py`)
+- Write your own adapter for Xero, QuickBooks, or anything else --
+  `sage_adapter.py` is about 100 lines and a reasonable template to
+  copy
+
+## Testing
+
+```bash
+pip install pytest
+pytest
+```
+
+The core test suite has no dependencies to mock -- it's all plain
+Python objects in, plain Python objects out.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| A statement line matches the wrong ledger invoice | Shouldn't happen -- recskit always tries an exact ref match before substring | If you see this, please open an issue with the two refs involved |
+| Balance agrees but you still see mismatches/missing items | This is expected and correct -- see "What problem this solves" above | Investigate each flagged line; a tied total doesn't guarantee every line is right |
+| Payment shows as missing despite being in the ledger | Amount differs by more than the tolerance, and the reference also doesn't appear as a substring | Widen `tolerance` in `match_payment()`, or check the payment was recorded correctly |
+| `ImportError` on `sagekit` | The `sage` extra wasn't installed | `pip install -e ".[sage]"`, or install sagekit directly |
+
+## License
+
+MIT -- see [LICENSE](LICENSE). Do whatever you like with this; a
+credit or a [Ko-fi tip](https://ko-fi.com/duckboard) is appreciated
+but never required.

recskit-0.1.0/README.md

@@ -0,0 +1,152 @@
+# recskit
+
+Reconcile a supplier or customer statement against your own accounting
+ledger: match invoices, credit notes, and payments; flag mismatches
+and missing items on either side; compare balances. The core has
+**zero dependencies** and doesn't care where your data came from --
+CSV, a PDF you parsed by hand, Sage, Xero, QuickBooks, anything.
+
+If this saves you time, consider [buying me a coffee](https://ko-fi.com/duckboard).
+
+## What problem this solves
+
+Checking a supplier statement against your own ledger by eye is slow
+and error-prone, especially once an account has more than a handful of
+open items. Two things make it worse than it looks:
+
+1. **A tied-up total balance doesn't mean every line is right.** Two
+   errors can cancel out -- a mismatched invoice and a missing one can
+   add up to the same total as if nothing were wrong. recskit checks
+   every line, not just the bottom-line figure.
+2. **Reference matching is a trap.** A short reference like `991` can
+   turn up as a *substring* of an unrelated, older invoice's reference
+   (`INV-99910`) on a long-standing account. Match on substring first
+   and you'll silently pair the statement line with the wrong invoice,
+   reporting a confident-looking "mismatch" instead of correctly
+   reporting no match at all. recskit always tries an **exact**
+   reference match before ever falling back to substring matching.
+
+## Features
+
+- Matches invoices/credit notes by reference (with support for
+  statements that print two references for the same line), payments
+  by amount first then reference
+- Exact-match-first, substring-fallback matching order -- see above
+- Configurable payment-terms due-date calculation (flat N days,
+  N days from the start of the following month, N days from end of
+  month, or end of the following month with no offset)
+- Flags items in your ledger that never show up on the statement at
+  all (commonly an old item sitting in a brought-forward balance)
+- Zero required dependencies in the core -- add the optional `sage`
+  extra only if you want the bundled Sage 50 adapter
+- Two worked examples: pure CSV (no external system at all), and Sage
+  50 via [sagekit](https://github.com/Duckboard/sagekit)
+
+## Installation
+
+```bash
+pip install -r requirements.txt      # core only, zero dependencies
+pip install -e .                     # or, as an editable package
+pip install -e ".[sage]"             # + the optional Sage 50 adapter
+```
+
+## Usage
+
+```python
+from recskit import StatementItem, LedgerInvoice, LedgerPayment, reconcile_statement
+
+items = [
+    StatementItem(type="invoice", ref="INV-100", amount=500.00),
+    StatementItem(type="invoice", ref="INV-101", amount=320.00),
+    StatementItem(type="payment", ref="bacs", amount=300.00),
+]
+
+ledger_invoices = [
+    LedgerInvoice(ref="INV-100", amount=500.00, outstanding=500.00),
+    LedgerInvoice(ref="INV-101", amount=300.00, outstanding=300.00),
+]
+ledger_payments = [LedgerPayment(ref="BACS-9001", amount=300.00)]
+
+result = reconcile_statement(items, ledger_invoices, ledger_payments, statement_balance=800.00)
+
+print(result.agreed, result.issue_count, result.balance_difference)
+for r in result.mismatched_items + result.missing_items:
+    print(r.item.ref, r.status, r.note)
+```
+
+### Payment-terms due dates
+
+```python
+from datetime import date
+from recskit import calc_due_date
+
+calc_due_date(date(2026, 5, 14), 30)                                   # 30 days from invoice date
+calc_due_date(date(2026, 5, 14), 29, "start_of_following_month")       # 29 days from 1 June
+calc_due_date(date(2026, 5, 3), 14, "end_of_month")                    # 14 days from 31 May
+calc_due_date(date(2026, 5, 3), 0, "end_of_following_month")           # 30 June, terms_days ignored
+```
+
+### Examples
+
+```bash
+python examples/reconcile_csv.py                         # runs on the bundled sample CSVs
+python examples/reconcile_csv.py statement.csv ledger.csv 1063.45   # your own files
+python examples/reconcile_sage.py                         # requires the "sage" extra + a live Sage 50
+```
+
+`reconcile_csv.py` needs no external system at all -- a good starting
+point for wiring recskit up to whatever export your own accounting
+software produces. `reconcile_sage.py` shows the same reconciliation
+against a live Sage 50 purchase ledger account, using
+`recskit.sage_adapter` to fetch the ledger side and
+[sagekit](https://github.com/Duckboard/sagekit) for the ODBC
+connection and column auto-detection.
+
+### Concept reference
+
+| Concept | Meaning |
+|---|---|
+| `StatementItem` | One line from the statement you're checking (invoice, credit note, or payment) |
+| `LedgerInvoice` / `LedgerPayment` | The equivalent transaction as it exists in your own ledger |
+| `MatchResult.status` | `"ok"`, `"mismatch"` (found but wrong amount), or `"missing"` (no match at all) |
+| `extra_in_ledger` | Ledger invoices never referenced by any statement line -- check these aren't being missed, or are simply old brought-forward items |
+| `balance_difference` | `ledger_balance - statement_balance` |
+
+## Bring your own data source
+
+The reconciliation logic never touches a database, file, or network --
+you build `StatementItem` / `LedgerInvoice` / `LedgerPayment` lists
+however suits your setup, and call `reconcile_statement()`. Options:
+
+- Parse a PDF or CSV statement export yourself (see
+  `examples/reconcile_csv.py`)
+- Pull the ledger side from Sage 50 with `recskit.sage_adapter` (see
+  `examples/reconcile_sage.py`)
+- Write your own adapter for Xero, QuickBooks, or anything else --
+  `sage_adapter.py` is about 100 lines and a reasonable template to
+  copy
+
+## Testing
+
+```bash
+pip install pytest
+pytest
+```
+
+The core test suite has no dependencies to mock -- it's all plain
+Python objects in, plain Python objects out.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| A statement line matches the wrong ledger invoice | Shouldn't happen -- recskit always tries an exact ref match before substring | If you see this, please open an issue with the two refs involved |
+| Balance agrees but you still see mismatches/missing items | This is expected and correct -- see "What problem this solves" above | Investigate each flagged line; a tied total doesn't guarantee every line is right |
+| Payment shows as missing despite being in the ledger | Amount differs by more than the tolerance, and the reference also doesn't appear as a substring | Widen `tolerance` in `match_payment()`, or check the payment was recorded correctly |
+| `ImportError` on `sagekit` | The `sage` extra wasn't installed | `pip install -e ".[sage]"`, or install sagekit directly |
+
+## License
+
+MIT -- see [LICENSE](LICENSE). Do whatever you like with this; a
+credit or a [Ko-fi tip](https://ko-fi.com/duckboard) is appreciated
+but never required.

recskit-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "recskit"
+version = "0.1.0"
+description = "Reconcile a supplier or customer statement against your accounting ledger: match invoices, credit notes, and payments, flag mismatches and missing items, compare balances. No dependencies in the core -- works with any data source."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+    { name = "Duckboard" }
+]
+dependencies = []
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business :: Financial :: Accounting",
+]
+
+[project.optional-dependencies]
+sage = [
+    "sagekit>=0.1.0",
+]
+parse-pdf = [
+    "pdfplumber>=0.10",
+    "anthropic>=0.30",
+]
+
+[project.urls]
+Homepage = "https://github.com/Duckboard/recskit"
+"Buy me a coffee" = "https://ko-fi.com/duckboard"
+
+[tool.setuptools.packages.find]
+include = ["recskit*"]

recskit-0.1.0/recskit/__init__.py

@@ -0,0 +1,45 @@
+"""
+recskit -- reconcile a supplier or customer statement against your own
+accounting ledger: match invoices, credit notes, and payments, flag
+mismatches and missing items, and compare balances.
+
+The core logic has no dependencies at all and doesn't care where your
+data came from -- CSV, a PDF you parsed by hand, Sage, Xero,
+QuickBooks. recskit.sage_adapter is one optional, concrete way to pull
+the ledger side out of Sage 50 (via sagekit); write your own equivalent
+for anything else.
+
+    from recskit import StatementItem, LedgerInvoice, LedgerPayment
+    from recskit import reconcile_statement, calc_due_date
+
+See README.md for the full walkthrough.
+"""
+
+from .due_dates import DUE_FROM_MODES, calc_due_date
+from .matching import find_best_name_match, match_invoice, match_payment, normalize_name
+from .models import (
+    LedgerInvoice,
+    LedgerPayment,
+    MatchResult,
+    ReconciliationResult,
+    StatementItem,
+)
+from .reconcile import reconcile_statement
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "StatementItem",
+    "LedgerInvoice",
+    "LedgerPayment",
+    "MatchResult",
+    "ReconciliationResult",
+    "reconcile_statement",
+    "match_invoice",
+    "match_payment",
+    "normalize_name",
+    "find_best_name_match",
+    "calc_due_date",
+    "DUE_FROM_MODES",
+    "__version__",
+]

recskit-0.1.0/recskit/due_dates.py

@@ -0,0 +1,77 @@
+"""
+recskit.due_dates
+==================
+Calculates an invoice's due date from its invoice date and a supplier's
+(or customer's) payment terms. Different trading partners quote terms
+in different ways -- "30 days", "29 days from the end of the month
+following", "last day of the month after invoice month" -- and getting
+this wrong is exactly what makes an "overdue" flag either useless
+(triggers too early) or dangerous (triggers too late).
+"""
+
+from datetime import date, timedelta
+
+# The four due-date conventions this covers. If a trading partner uses
+# something not listed here, "invoice_date" (a flat N days from the
+# invoice date) is the safest fallback -- it's the most common by far.
+DUE_FROM_MODES = (
+    "invoice_date",
+    "start_of_following_month",
+    "end_of_month",
+    "end_of_following_month",
+)
+
+
+def _last_day_of_month(year: int, month: int) -> date:
+    if month == 12:
+        return date(year, 12, 31)
+    return date(year, month + 1, 1) - timedelta(days=1)
+
+
+def calc_due_date(invoice_date: date, terms_days: int, due_from: str = "invoice_date") -> date:
+    """
+    Calculate an invoice's due date.
+
+    due_from options:
+        "invoice_date"             -- N days from the invoice date
+                                       (the default, and most common)
+        "start_of_following_month" -- N days from the 1st of the month
+                                       after the invoice date, e.g.
+                                       "29 days" meaning the 30th of
+                                       the month after next
+        "end_of_month"             -- N days from the last day of the
+                                       invoice's own month, e.g.
+                                       "14 days EOM"
+        "end_of_following_month"   -- the last day of the month AFTER
+                                       the invoice month, no day offset
+                                       (terms_days is ignored for this
+                                       mode -- it's a fixed rule, e.g.
+                                       "last day of the month following
+                                       the invoice")
+
+    Raises ValueError for an unrecognised due_from value, rather than
+    silently falling back to a default -- an unnoticed typo here would
+    quietly miscalculate every due date for that trading partner.
+    """
+    if due_from not in DUE_FROM_MODES:
+        raise ValueError(f"Unknown due_from {due_from!r} -- must be one of {DUE_FROM_MODES}")
+
+    if due_from == "start_of_following_month":
+        if invoice_date.month == 12:
+            first_next = date(invoice_date.year + 1, 1, 1)
+        else:
+            first_next = date(invoice_date.year, invoice_date.month + 1, 1)
+        return first_next + timedelta(days=terms_days)
+
+    if due_from == "end_of_month":
+        return _last_day_of_month(invoice_date.year, invoice_date.month) + timedelta(days=terms_days)
+
+    if due_from == "end_of_following_month":
+        if invoice_date.month == 12:
+            target_year, target_month = invoice_date.year + 1, 1
+        else:
+            target_year, target_month = invoice_date.year, invoice_date.month + 1
+        return _last_day_of_month(target_year, target_month)
+
+    # "invoice_date"
+    return invoice_date + timedelta(days=terms_days)

recskit-0.1.0/recskit/matching.py

@@ -0,0 +1,116 @@
+"""
+recskit.matching
+=================
+Matches individual statement lines against ledger transactions.
+
+The core lesson baked into this module: **always try an exact
+reference match before falling back to a substring match.** A short
+reference like "9910" can accidentally turn up as a *substring* of an
+unrelated, older invoice's reference on a long-standing account. If you
+match on substring first, you silently pair the statement line with
+the wrong ledger invoice -- and report a confident-looking "mismatch"
+amount instead of correctly reporting no match at all. This bit a real
+reconciliation run before the exact-match-first rule was added, so
+it's not a hypothetical -- keep the ordering.
+"""
+
+import re
+from typing import List, Optional, Tuple
+
+from .models import LedgerInvoice, LedgerPayment, MatchResult, StatementItem
+
+
+def normalize_name(name: str) -> str:
+    """
+    Strip everything except letters and digits and uppercase the rest.
+    Account/company names are rarely entered consistently ("N.D. John"
+    vs "ND John", "St." vs "St", extra spaces) -- comparing on
+    letters/digits only avoids false negatives from punctuation alone.
+    """
+    return re.sub(r"[^A-Z0-9]", "", (name or "").upper())
+
+
+def find_best_name_match(
+    search_term: str, candidates: List[Tuple[str, str]], tie_breaker_counts: Optional[dict] = None
+) -> Optional[Tuple[str, str]]:
+    """
+    Find the best match for `search_term` among `candidates`, a list of
+    (id, name) tuples, using normalize_name() for a punctuation-
+    insensitive comparison.
+
+    Returns the matching (id, name) tuple, or None if nothing matches.
+    If more than one candidate matches, `tie_breaker_counts` (a dict of
+    id -> some comparable score, e.g. transaction count) picks the
+    highest-scoring one; without it, the first match wins.
+    """
+    norm_search = normalize_name(search_term)
+    matches = [c for c in candidates if norm_search in normalize_name(c[1])]
+
+    if not matches:
+        return None
+    if len(matches) == 1 or not tie_breaker_counts:
+        return matches[0]
+
+    return max(matches, key=lambda c: tie_breaker_counts.get(c[0], 0))
+
+
+def match_invoice(
+    item: StatementItem, ledger_invoices: List[LedgerInvoice], tolerance: float = 0.01
+) -> MatchResult:
+    """
+    Match one invoice/credit-note statement line against the ledger.
+
+    Tries an exact match on `ref` (and `alt_ref`, if the statement
+    supplied a second reference for this line) first. Only if nothing
+    matches exactly does it fall back to a substring match -- see the
+    module docstring for why the ordering matters.
+    """
+    refs_to_try = [item.ref.upper()]
+    if item.alt_ref:
+        refs_to_try.append(item.alt_ref.upper())
+
+    exact = [inv for inv in ledger_invoices if inv.ref.upper() in refs_to_try]
+    candidates = exact or [
+        inv for inv in ledger_invoices if any(r in inv.ref.upper() for r in refs_to_try)
+    ]
+
+    if not candidates:
+        return MatchResult(item=item, status="missing", note=f"No ledger entry for ref {item.ref!r}")
+
+    ledger_invoice = candidates[0]
+    if abs(ledger_invoice.amount - item.amount) < tolerance:
+        return MatchResult(
+            item=item, status="ok", ledger_ref=ledger_invoice.ref, ledger_amount=ledger_invoice.amount
+        )
+
+    return MatchResult(
+        item=item,
+        status="mismatch",
+        ledger_ref=ledger_invoice.ref,
+        ledger_amount=ledger_invoice.amount,
+        note=f"Statement £{item.amount:,.2f} vs ledger £{ledger_invoice.amount:,.2f}",
+    )
+
+
+def match_payment(
+    item: StatementItem, ledger_payments: List[LedgerPayment], tolerance: float = 0.01
+) -> MatchResult:
+    """
+    Match one payment statement line against the ledger.
+
+    Payments are matched by **amount first**, then by reference text --
+    the opposite order to invoices. This is deliberate: payment
+    references (BACS refs, bank descriptions) very often differ
+    between what a supplier's statement shows and what actually lands
+    in your ledger, whereas the amount is reliable.
+    """
+    by_amount = [p for p in ledger_payments if abs(p.amount - item.amount) < tolerance]
+    candidates = by_amount or [
+        p for p in ledger_payments if item.ref and item.ref.upper() in (p.ref or "").upper()
+    ]
+
+    if not candidates:
+        return MatchResult(item=item, status="missing", note=f"No ledger payment matching £{item.amount:,.2f}")
+
+    payment = candidates[0]
+    return MatchResult(item=item, status="ok", ledger_ref=payment.ref, ledger_amount=payment.amount)