Home › Use Cases › Verify one merchant's reserve balance against the reserve terms in the merchant agreement
Use caseUC0348
🧪 Use-case kit · runnable

Verify one merchant's reserve balance against the reserve terms in the merchant agreement

A small, forkable project that does one job end to end. Run once for real, and every figure on these pages captured from that run.

The business caseThe problem this solves

An acquirer holds a reserve against a merchant's exposure, and the merchant agreement says exactly how much: a rolling percentage of a named settlement base, taken batch by batch, held for a stated period, capped at a stated ceiling, with chargebacks and chargeback fees debitable against it and interest credited only where the agreement provides for it. The portfolio system then posts takes, releases, debits and credits to a reserve ledger and prints a position on the merchant's statement. Whether that position is what the terms require is a question somebody has to answer account by account — and the ledger's own STATUS column is not the answer: a row can read POSTED and still be money that never moved, a fee the reserve does not secure, or interest on an agreement that provides none. Under-collect and the acquirer is exposed; over-hold and it is the merchant's own working capital sitting behind a term that does not support it. Opening one merchant's reserve statement, adding the settlement base up by hand, applying the rolling rate batch by batch, walking the holding period across a calendar to see which carried-in takes have matured, reading every note printed under a ledger row to decide whether the money actually moved, checking each fee debit against the agreement's recourse line, and then deciding whether the gap is inside tolerance or over both escalation bars.

Audience

An acquirer's or PSP's risk-operations desk working a monthly reserve verification list, and the portfolio analyst behind it who has to say why a figure moved. Every number on these pages came from one real run of this code, not from a vendor page.

The inputThe actual reserve verification files

The corpus is 65 reserve verification files, 0.25 MB (txt 65). It is generated because it has to be. A real reserve statement is a merchant's own trading position and its acquirer's own risk file, and the exact shapes measured here — a take reversed at the funding desk, a release stood down by the risk desk, a relationship manager asking for the principal to be named — are the rows neither party would ever want published. What the generator buys back is an answer key DERIVED from the structure each file was rendered from rather than typed, re-derived a second time by an independent checker with its own calendar, at 0 disagreements and red-proven eight ways.

The corpus

  • The 65 reserve verification filesgenerated from a fixed seed, so no real record, person or institution appears in it.
  • Where each came fromdata/SOURCES.md carries the case mix, the note pools, what the generator costs the measurement and the eight red-proofs of the key.

Swap this folder for your own material and the kit is pointed at your reserve verification files. That is the whole change — there is no database to migrate.

One reserve verification file, as the model receives itRSV-0001.txt · 1 of 65
==============================================================================
RESERVE VERIFICATION FILE                                  RSV-0001
Portfolio: PRT-04 - Northbank Acquiring (invented)
Merchant: MID-40003   Ridgeline Outfitters   Period: 2026-04-01 to 2026-04-30   Procedure: RSV-2026
As at: 2026-04-30   Agreement: MA-8001   Reserve schedule: R-1
==============================================================================

MERCHANT AND TERMS AS THE PORTFOLIO MASTER HOLDS THEM
  settlement currency       USD
  reserve rate                       6.500   pct of the settlement base
  reserve cap                      5780.70
  holding period                       180   days
  settlement base           net settled volume
  debit recourse            chargeback and chargeback fees only
  interest provision        none
  opening reserve balance          4134.59
  tolerance pct                       0.50   pct of required
  threshold cost                  10000.00   or more
  threshold pct                       5.00   pct or more
  period                    full-month

SETTLED BATCHES IN THE PERIOD AS THE SETTLEMENT SYSTEM REPORTS THEM
  BATCH      VALUE DATE    SETTLEMENT BASE
  BAT-0001   2026-04-02            8459.98
  BAT-0002   2026-04-08            1337.01
  BAT-0003   2026-04-14            9471.27
  BAT-0004   2026-04-20            6943.15
  BAT-0005   2026-04-26            3433.26

TAKES CARRIED IN FROM BEFORE THE PERIOD
  TAKE       VALUE DATE             AMOUNT
  PT-0001    2025-09-01            1000.67
  PT-0002    2025-07-30            2982.30
  PT-0003    2025-10-21             151.62

RESERVE LEDGER AS POSTED BY THE PORTFOLIO SYSTEM
  MOVEMENT   DATE               AMOUNT  KIND              STATUS    REF          MEMO

Abridged — the file continues.

The outcomeWhat a good result looks like

One account in, one row out: which ledger rows this procedure treats differently from the ledger that printed them with each row quoted verbatim, whether the printed reserve schedule was the rate in force, the balance the ledger really holds, the balance the terms require, the gap, and one verdict from a closed five-value ladder. 49 of 65 accounts came back with every one of the five graded fields right, against 31 for the best arm that costs nothing.

And when it cannot

And what it does when it cannot. On the scored run 65 of 65 replies parsed and nothing stopped at the ceiling, so there is no unparsed column to report. What there IS to report is that every one of the 16 misses is an OVER-CITATION: across 65 files the arm missed exactly ONE labelled row and invented 17, ten of the misses being pure over-citation on a file whose key is empty. An account whose reply cannot be read at all is counted WRONG and stays in the denominator; a reply that stopped at the ceiling is a failure, not a partial score.

Where it fitsWhat did work

Every line below is a measured result from this kit's own runs, with the figure that supports it. The headline above is not softened by any of them.

  • your reserve ledger's bad rows announce themselves in a status or a reason code — the free column parser
    31 of 65 for nothing, and on a ledger whose reversals are structured it would be 65 of 65
  • your ledger's bad rows are only ever described in a note, in English — this kit
    18 of the 24 accounts where the portfolio system is wrong, against 0 for the page and 9 for the best keyword rule
  • you want to confirm that a clean portfolio is clean — the free floor
    17 of 17 on the accounts with nothing wrong, against the paid arm's 13. The call finds faults that are not there.
  • your reserve amendments live in a contract record rather than in prose — a lookup, and keep this kit for the ledger half
    T-8 is the one reading a deployment can remove entirely by refusing an amendment from the notes field and requiring it from the agreement record
  • you need the verdict to follow the agreement rather than a model's judgement — the station, whichever arm feeds it
    every published verdict is derived by src/terms.py from the ordered rule table; the arm's own verdict is right on 32 of 65 and the derived one on 56

At a glanceHow the whole thing runs

75%all five fields right pct
1,680 msp50, end to end
$0.00per 1,000 reserve verification files · google/gemini-3-flash

Run once, for real, on 2026-09-09. Every figure on these pages was captured from that run — nothing is written from intent.

14 steps, grouped by the question that sends you to them rather than by build order. Each tile carries the one figure that step is about, and opens the page behind it.

Should you use this?What you bring, where it stops, and when not to use it

Before you commit an afternoon to this, these are the answers that decide it. Each one is rendered from the record it lives in — and links the page that holds it in full.

What do I have to bring?Replace data/corpus/*.txt with your own reserve statements in the same shape and data/merchants.json with your own portfolio register. ⚠︎ WHAT STOPS BEING TRUE THE MOMENT YOU DO. Corpus lens →
When is this the wrong choice?Avoid: Paying for a reading that a lookup already answers. That is the case against the best-fitting scenario (“your reserve ledger's bad rows announce themselves in a status or a reason code”). 5 scenarios scored in all, each with its own. Eval lens →
Where does it stop working?a reserve ledger whose notes are a code rather than a sentence. The whole reading here is that a POSTED row's note is written in ordinary English; a portfolio system that posts a structured reversal reason needs no model at all. 6 recorded failure modes, each from a run rather than a guess. Corpus lens →
What was never verified?the run-to-run spread on this corpus. ONE scored run was fired, so nothing here says how much of the 49 is stable. 8 items this kit says it could not check. Eval lens →
Can I run this on a model I control?Yes — any OpenAI-compatible endpoint, including one on your own hardware. The shipped adapter takes its host from BASE_URL and its model from MODEL, so nothing in src/ changes. The published figures come from 1 model on the fast tier, one provider, one key. Prompt lens →
And if it fits — what do I stand up?6 artifacts with a stated home and a stated egress, and 3 decisions each with what you provision past its ceiling — plus what was not measured. That is the next page, not this one. step 14 — Run it in your environment →

Not asked of this kit — 2 questions: clone (a fresh clone of this kit runs with nothing fetched); judge (nothing here is graded by a model).

Last verified 2026-09-09 — r001-reserve-balance. Every figure on these pages was captured from that run.

Run itHow this reaches your data

Every result on this page was produced by pure code over checked-in files, with no API key — which is why you can read the numbers before anyone spends anything.

Run this on your own data

  • The pipeline, its eval harness and the runs behind every numberdeployed inside your environment, on your own model endpoints, against your own documents.
  • The corpus above is the shape, not the limitit is a folder swap, and there is no database to migrate.

Talk to us →

Checked before this shipped — A clean checkout with no key configured renders the whole board, all four free floors, all six committed runs, the procedure panel and the prompt decomposition. python3 tools/build_corpus.py --check and python3 -m evals.check_labels both run with nothing installed.

A living map of modern AI — kept current every morning