Home › Use Cases › Reconcile a card network's monthly fee invoice against the schedule in force and activity
Use caseUC0448
🧪 Use-case kit · runnable

Reconcile a card network's monthly fee invoice against the schedule in force and activity

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

A card network bills an acquirer every month for authorization, clearing, volume, chargeback and verification fees, and before the invoice is paid the acquirer's network billing desk has to agree it with three other records: the fee schedule version in force for that month, the schedule rows that version and its bulletin corrections carry, and the acquirer's own billable activity by fee driver. The acquirer's invoice check reads those records' COLUMNS — a register STATUS, a rate on a row, a batch status on the clearing extract. What decides the answer is often a sentence: a bulletin that replaced or deferred a version, retired a fee code or rescinded a correction, a clearing note that a posted batch was reversed or re-run, a held batch released before AS AT. The acquirer's own check disagrees with the procedure on 34 of the 64 invoices in this corpus. Opening one invoice pack, deciding which fee schedule version was in force for the month from the register and every bulletin, listing the rows that version and its live corrections carry, working out which clearing batches were billable at AS AT after reversals, re-runs and releases, and then checking every invoice line's count, rate and version against those three and looking for billable activity the network never invoiced.

Audience

The network billing desk at a card acquirer, working a month's network fee invoices before the payment run — and the finance manager who approves payment release, which this kit never does. Every number on these pages came from one real run of this code, not from a vendor page.

The inputThe actual network fee invoices

The corpus is 64 network fee invoices, 0.31 MB (txt 64). It is generated because it has to be. A real network fee invoice book is an acquirer's own commercial record under a network agreement: negotiated fee schedules that are confidential, member ids, clearing batches, and bulletins a network publishes to its members only. None of that can be published, and a corpus that could be published would have had the one thing this kit measures — the bulletin or clearing note that decides a reading — stripped out first. So the whole thing is invented, declared, and generated from one seed with the key DERIVED by the same rulebook the kit applies.

The corpus

  • The 64 network fee invoicesgenerated from a fixed seed, so no real record, person or institution appears in it.
  • Where each came fromdata/SOURCES.md states where every byte came from AND what the generator costs the measurement, and records the failures named before the first call next to what actually happened. The three networks, the twelve acquirers, every fee code, schedule, bulletin, batch and invoice are invented, and THERE ARE NO PEOPLE IN THIS CORPUS AT ALL — a note speaks for a network bulletin, network billing, clearing operations, the billing desk or the treasury desk. evals/check_labels.py sweeps all 64 files for a person-shaped name and an honorific on every run and reports 0.

Swap this folder for your own material and the kit is pointed at your network fee invoices. That is the whole change — there is no database to migrate.

One network fee invoice, as the model receives itNFI-0001.txt · 1 of 64
================================================================================
NETWORK FEE INVOICE RECONCILIATION -- ONE INVOICE, ONE AS-AT DATE
================================================================================
FILE              NFI-0001
NETWORK           NW-1  Orrinvale Card Network
ACQUIRER          AQ-6101  Tallowbrook Merchant Acquiring
MEMBER ID         MBR-41000
INVOICE           OV-2606-41000
INVOICE DATE      2026-07-02
BILLING MONTH     2026-06 (2026-06-01 to 2026-06-30)
AS AT             2026-07-06
PACK COMPILED     2026-07-09
PAYMENT DUE       2026-07-17  (operator-supplied)
DISPUTE WINDOW    30 days from the invoice date  (operator-supplied)
CURRENCY          USD

-- FEE SCHEDULE REGISTER (every version this acquirer was notified of) ---------
VERSION     EFFECTIVE   STATUS      LOADED ON
FS-2026.1   2026-01-01  LOADED      2025-12-03
FS-2026.2   2026-06-01  LOADED      2026-05-20
FS-2026.3   2026-09-01  NOT LOADED  --

-- FEE SCHEDULE ROWS (every row of every LOADED version, and bulletin corrections) ---
ROW       VERSION    CODE    DRIVER     UNIT             RATE  EFFECTIVE   SOURCE
FSR-0016  FS-2026.1  OV-110  AUTH-DOM   per item       0.0185  2026-01-01  FS-2026.1 schedule
FSR-0000  FS-2026.1  OV-120  AUTH-XB    per item       0.0450  2026-01-01  FS-2026.1 schedule
FSR-0028  FS-2026.1  OV-210  CLR-DOM    per item       0.0120  2026-01-01  FS-2026.1 schedule
FSR-0031  FS-2026.1  OV-310  VOL-DOM    pct volume    0.1300%  2026-01-01  FS-2026.1 schedule
FSR-0009  FS-2026.1  OV-320  VOL-XB     pct volume    0.6000%  2026-01-01  FS-2026.1 schedule
FSR-0021  FS-2026.2  OV-110  AUTH-DOM   per item       0.0195  2026-06-01  FS-2026.2 schedule
FSR-0003  FS-2026.2  OV-120  AUTH-XB    per item       0.0460  2026-06-01  FS-2026.2 schedule

Abridged — the file continues.

The outcomeWhat a good result looks like

One invoice pack in, one row out: the fee schedule version in force, the schedule rows in force, the billable activity, every line's flags, the recomputed amount to the cent, every exception and one of seven NFR-2026 verdicts — or a BLOCK when the version in force is not held. 50 of 64 invoices come back with all six graded fields right, against 40 for the best free floor and 0 for the acquirer's own check — and that whole-invoice margin is NOT statistically significant (18 against 8 discordant invoices, p = 0.0755). The verdict margin is: 58 against 40, p = 0.00028.

And when it cannot

And what it does when it cannot. On the scored run 64 of 64 replies parsed, 0 stopped at the ceiling and no call failed. It got 14 invoices wrong and every one is a reading. Two are the candidate's own guardrail: on NFI-0036 and NFI-0054 the register prints the version in force NOT LOADED, and the reply took the prior version as in force instead of blocking, so the station reported rate variances on a month that should not have been reconciled at all. One is the costly direction: NFI-0011 bills a retired fee code and came back RECONCILED. Six leave out one bulletin correction row effective after the billing month, with the verdict and amount still right on five. A reply that cannot be parsed is counted WRONG and stays in the denominator; it is never dropped and never re-fired.

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 network publishes schedule changes as register rows and your clearing extract carries reversals, re-runs and releases as batch statuses — the free modal floor, and do not buy a call at all
    40 of 64 invoices for $0.00. Stale and early versions, count variances, held batches, undefined codes, unbilled activity and a register that prints NOT LOADED are all decidable from columns and dates, and on those 37 invoices the floor gets 37.
  • Bulletins replacing, deferring or retiring things arrive as free text, and clearing operations reverse or re-run batches by note — the paid call
    This is the whole product. On the 27 invoices where a sentence decides a reading the paid arm is 21, the modal floor 3 and the best vocabulary floor 10; on bulletin-replaced versions it blocks 4 of 4 against the best floor's 2.
  • A missing fee schedule version must never be assumed — the paid call AND a code check on the register beside it
    The paid call assumed a prior version on 2 of the 7 invoices that must block — NFI-0036 and NFI-0054, both where the register prints the version in force NOT LOADED. A station rule that blocks whenever the register prints a version NOT LOADED effective on or before the month start fires on exactly those 3 register packs in this corpus, with 0 false blocks, and would have turned both misses into the block. It is not built.
  • You want to catch the invoice passed as RECONCILED that is not — the paid call
    The station returned RECONCILED on an exception invoice once in 64 from the paid readings (NFI-0011, a retired fee code kept) against 11 from the modal floor's.
  • You want the acquirer's own invoice check audited — either paid or free — both beat it comprehensively
    The check's status disagrees with NFR-2026 on 34 of 64 invoices and gets 0 whole: it returns no reading at all. It is published as an arm so the comparison is against what is running today rather than against nothing.

And where nothing here is good enough:

  • Your invoices split fee codes across lines, price mid-month versions or carry a rounding tolerance — neither, yet
    No pack in this corpus does. The unit of work is one line per fee code, versions effective on the first of a month and exact cents, and every percentage on this page is against that unit.

At a glanceHow the whole thing runs

78%rechecked all correct pct
1,970 msp50, end to end
$1.71per 1,000 network fee invoices · the fast tier

Run once, for real, on 2026-09-13. 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 invoice packs in the same block shape and data/register.json with your own member register, then run python3 -m evals.run --run-id b000-<yours>-modal --floor modal — it needs no key and costs nothing. ⚠︎ WHAT STOPS BEING TRUE THE MOMENT YOU DO. Corpus lens →
When is this the wrong choice?Avoid: Paying per invoice for arithmetic you already have. That is the case against the best-fitting scenario (“Your network publishes schedule changes as register rows and your clearing extract carries reversals, re-runs and releases as batch statuses”). 6 scenarios scored in all, each with its own. Eval lens →
Where does it stop working?A fee schedule register with no STATUS or no effective date. R-1 decides the version in force from the register and the bulletins; a version with no loaded status or no date has nothing to hold against the billing month. 7 recorded failure modes, each from a run rather than a guess. Corpus lens →
What was never verified?WHETHER IT BEATS FREE CODE ON THE WHOLE INVOICE. 50 against 40 of 64 is not significant (p = 0.0755); only the verdict margin is (58 against 40, p = 0.00028). 11 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?5 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-13 — r001-network-fee. 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, runs all four free floors through the station on any invoice and replays every committed run. pip install -r requirements.txt installs nothing — the kit is standard library only. The only thing a key buys is the ASK THE MODEL button and a new scored run.

A living map of modern AI — kept current every morning