# TB · Tabula, billing

**Status:** TB-1 to TB-7 decided by the Architect on 6 November 2026 (plan IA §8); **TB-8 to TB-15 decided as recommended
on 7 November 2026.** TB-16 (complimentary by default; billing for one organisation) decided the same day. Mockups drawn,
redrawn and **approved by the Architect on 7 November 2026** (§5). Slices in §6. What Desk and Atrium do was
read from their code; nothing was run. **Built 7 and 8 November 2026, TB1 to TB6**; the money paths reviewed in
`reji/docs/SECURITY_REVIEW_TABULA.md`. Before live money: E-VAT access, the VAT registration, refunds and credit notes, and withholding's review step.
**Money back (§7): TB-17 to TB-22 decided as recommended by the Architect on 8 November 2026**; mockups approved the same day;
TB7 to TB9 built 8 November 2026, and the money paths reviewed again (7.7 of 10). **Money back is built.**

## 0 · What Tabula is, what it covers, and how things carry on without it

**In simple terms.** Tabula is how the company charges its own customers for its products. An organisation picks a plan
for a product at `id`, pays by card or mobile money through Paystack, gets a tax invoice and a receipt, and the product
learns what the organisation is entitled to. When a period isn't paid, the organisation drops to the product's Free plan;
nothing is locked or deleted. It is not the money a product collects from *its* customers (school fees, dues), which is
Aerarium's, later.

**Its scope.**

| Atrium (Tabula) handles | The product handles |
|---|---|
| The catalogue's prices: each offering's monthly and yearly price, and an agreed price for one organisation (TB-1) | Nothing about prices |
| Which offering an organisation holds, from when to when (`entitlement`), and what that offering includes and allows, as data | **Enforcing** what the offering includes and allows (seats, storage, features), since only the product knows what they mean |
| Paying: the checkout at Paystack and back, card renewals by our own scheduler, mobile money paid ahead with reminders | Showing a banner or a limit inside itself, from what Atrium told it |
| Tax invoices and receipts with VAT on separate lines, cleared through the GRA's E-VAT, and withholding with its certificate (TB-5) | Nothing about tax |
| Falling back to Free when a period goes unpaid (TB-3); the switch that keeps it all dark until prices are set (TB-2) | Carrying on within Free's limits |
| The billing role at `id` (owner and billing see it; admins don't), and telling the organisation by mail | Who uses it inside, and their roles (CL-16) |
| SMS credits stay in Nuntius with its wallets, using the same checkout later (TB-6) | · |

**Its failsafe if Atrium is down for a while.**

| What stops | What carries on |
|---|---|
| Starting, changing or paying for a plan | Every organisation keeps what it holds: a product keeps the last entitlement it was told (offering, `ends_on`, what it includes) and serves it |
| Paystack's webhook can't reach us | Paystack retries for up to 72 hours, and every payment is also verified by its reference when the person returns and by a scheduled check, so a payment is never lost and never settled twice |
| A renewal falls due during the outage | It runs when Atrium is back. No organisation drops to Free while Atrium is down: the fall-back waits a grace period after `ends_on` (TB-11), counted by Atrium, never by the product's clock alone |
| E-VAT is down | The payment stands and the period starts; the invoice is cleared when the GRA answers, retried, and the Service is told if it keeps failing |

## 1 · What's decided

From plan IA §8 (TB-1 to TB-7), Clavis (the billing role, CL-16) and plan IA's rules for `id`:

- **TB-1** A list price per offering, monthly and yearly, with an agreed price possible for one organisation.
- **TB-2** Built now behind one switch; on when prices are set and the public site's "nothing is charged without a written
  agreement" has changed.
- **TB-3** An unpaid period falls back to the product's Free offering; nothing is deleted.
- **TB-4** Organisations on agreed terms keep them until the agreement ends, with a grace period and a founding price
  available.
- **TB-5** Tutelora Limited, Paystack, cedis; VAT from the first charge at an effective 20% on separate lines; invoices
  through the GRA's E-VAT; a school may withhold (`reji/docs/reference/tax-ghana.md`).
- **TB-6** SMS credits stay in Nuntius.
- **TB-7** One billing account per organisation to start, kept separate so a second can come.
- **IA §6** Payment leaves `id`: people go to Paystack's hosted page, and no provider script runs on `id`.
- **CL-16** A billing role apart from admin; Clavis added the `billing` standard role with no permissions yet.

## 2 · What exists

**In Atrium.** The catalogue (`product`, `offering`), what an organisation holds (`entitlement`, granted for a year, one
active per product), where it runs (`instance`), monthly usage limits for Atrium's own modules (`usage_limit`), the
console's grant, and `entitlement.granted` sent to products. Joining starts a product on its Free offering (CL4). Nothing
yet ends an entitlement when its year is up, and offerings carry no price, limit or feature.

**In Desk (M18b, built 8 October 2026, never run on a server).** Plans as data with monthly and yearly prices, limits and
included features; one row per paid period; card renewals by its own scheduler from Paystack's saved authorization; mobile
money paid ahead with reminders; upgrades at once with unused days credited, downgrades at the next period; invoices and
receipts numbered and kept as issued; a VAT setting ("none until registered", which TB-5 corrects); a dated switch-on with a
grace period and a founding price; the `log` gateway so development never calls Paystack. It reads through Desk's own
tenancy, and its plans have no product, so it comes across rewritten, with its tests.

**New work from Ghana's law** (TB-5): invoices cleared through E-VAT by API before they're issued; a payment net of 7.5%
withholding tax or 7% withholding VAT, with the certificate to follow (TB-15); rates as dated data.

## 3 · Decisions

**Decided by the Architect, 7 November 2026: TB-8 to TB-15, as recommended.**


| # | Decision | Recommended | Alternative |
|---|---|---|---|
| **TB-8** | When a year ends on Free | **Free renews itself**: its `ends_on` rolls on a year at a time, with nothing to do and nobody told | Free must be renewed, which flushes out dead organisations but risks a live school losing a product it didn't notice expiring |
| **TB-9** | What a paid period is | **Monthly or yearly, chosen at checkout.** A card renews itself; mobile money is paid ahead, reminded 14, 7 and 1 days before (Desk) | Yearly only, which suits schools' budgets but makes the first payment large |
| **TB-10** | Where an offering's limits and features live | **As data on the offering in Atrium**, told to the product with the entitlement (webhook and `GET /v1`), and enforced by the product | Each product keeps its own plan table, which drifts from what was sold |
| **TB-11** | When an unpaid period ends | **A grace period after `ends_on`**, a setting (7 days to start), with the organisation told at the start and the end; then the fall-back to Free (TB-3) | Fall back on the day, which punishes a slow mobile-money payment |
| **TB-12** | Changing plan mid-period | **Desk's rule**: an upgrade starts at once with the unused days credited; a downgrade at the next period | Everything at the next period, simpler but slow for a school that needs more now |
| **TB-13** | Switching billing on | **Per product**, since products go live at different times: a setting at the product's level, off as shipped, with Desk's dated announcement, grace and founding price for the organisations already on it | One switch for every product (TB-2 as worded), which forces every product live together |
| **TB-14** | Issuing a tax invoice | **Numbered at payment, cleared through E-VAT by a queued job**, the GRA's mark and QR on the PDF once cleared; a failure retries and tells the Service. Built behind a driver, with a `log` one for development, as Desk does for Paystack | Issue nothing until the GRA clears it, which stops a paid school getting any paper while E-VAT is down |
| **TB-15** | A payment net of withholding | **The period starts on the net payment; the withheld part stays open for 30 days** (a setting) until its certificate is uploaded, and the Service is told when it lapses | The period starts only when the certificate is in, which holds a school's product hostage to paperwork |

**TB-16, the Architect, 7 November 2026: complimentary by default, and billing for one organisation.** Until a product's billing
is switched on (TB-13), every organisation's subscription to it is **complimentary**: the word people see ("Your subscription is
complimentary"). The Service can charge **one organisation** from the console, **effective immediately**, while the rest stay
complimentary.

Confirmed by the Architect the same day, all three (drawn in `console.html`, state "Billing for one organisation"):
- **A setting per organisation and product with three values**: *As the product* (the default), *Charged from today*,
  *Complimentary for good*. They're code, not Input Fields: each changes what Atrium does (the house rule on lists). The third is the same control turned round: a launch partner kept free after the product
  starts charging, without a zero agreed price.
- **The grace days to choose a plan** (TB-11's setting, 7 to start): charged from today means plans and prices show at once,
  and the organisation keeps everything until it chooses; with no plan chosen it moves to Free, and nothing is deleted.
- **"Agreed with" is required and audited**, and the organisation's owners and billing people are told by e-mail at once.
  The complimentary page no longer promises "60 days' notice": an organisation charged by agreement gets none, so it says
  "Told first". The product-wide switch keeps its 60 days.

## 4 · Facts only the Architect has

None blocks building; all come before billing is switched on.

- The prices, and each product's Free offering and its limits.
- Tutelora's VAT registration, its E-VAT batch and API access from the GRA, and its own live Paystack account (mobile money
  on).
- Which organisations are on agreed terms, and until when (TB-4).
- The public site's terms changed from "nothing is charged without a written agreement".

## 5 · Mockups (`reji/ui/html/tb/`)

Starting from Desk's `m18b` set: plans side by side, per product; paying, leaving for Paystack and back (paid, failed,
abandoned); your subscription (active, renews on, mobile money ending soon, renewal failed, fell back to Free); invoices and
receipts with the tax lines and the GRA's QR; withholding, paying net and recording the certificate; what a billing-only
person sees at `id`; and in the console, offerings and prices, an agreed price for one organisation, and switching billing on
for a product.

**Drawn, 7 November 2026,** by `reji/ui/html/tb/build-mockups.py`, one file per concept, each state on the switcher, light and
dark, and the phone. **Redrawn the same day** after the Architect called the first set "standard boring and bland": each page is
now built around one picture of the reader's situation. Billing draws each product's year as a ribbon (paid, today, the renewal,
the grace days, Free after) that zooms to the weeks that matter when something is due. Plans rise as a staircase with Jaeda's
place pinned on it. The order is a ticket that gets stamped paid, declined or waiting. The money is drawn as split bars (the tax,
what was withheld), and the GRA's clearance is a seal. Switching billing on is a dated launch with its e-mail.

- `plans.html`: on Free (TuteCampus), on a paid plan (TuteBooks), an agreed price, complimentary (TuteLoop), and one
  organisation charged from today while the rest stay complimentary.
- `pay.html`: check and pay (monthly or yearly, card or mobile money, the tax lines), moving up mid-year with the unused days
  counted off, off to Paystack, paid, declined, came back without paying, mobile money waiting.
- `subscription.html`: the organisation's Billing: paying, mobile money ending in 7 days, a renewal failed, the grace days, back
  on Free (nothing deleted), and what Efua, billing only, sees.
- `invoice.html`: invoices and receipts, a tax invoice with the GRA's mark and QR, a receipt waiting for E-VAT, paying net of
  withholding, a certificate to send.
- `console.html`: offerings and prices per product, an offering's prices and what it allows, an agreed price for one
  organisation, switching billing on for TuteLoop (blocked until E-VAT is connected), and billing for one organisation
  (TB-16), with the organisations on their own terms listed under the offerings.

Choices the mockups make, for the Architect to confirm or change: prices are examples; withholding is worked on the price
before tax (`tax-ghana.md` leaves it open); a declined payment or an abandoned checkout changes nothing; a mid-year upgrade
credits the unused days against the price before tax is added; the console gets its own Billing menu item; and the plans and
Billing pages show places used (112 of 150 pupils, 6 of 10 projects), which needs the product to report its counts to Atrium:
if that isn't wanted, those lines go.

## 6 · Order

1. ☑ The discussion, TB-1 to TB-16, decided by the Architect, 6 and 7 November 2026.
2. ☑ Mockups drawn, redrawn after review, and approved by the Architect, 7 November 2026.
3. ☐ The slices below, in order (TB1 built 7 November 2026; TB2 built 8 November 2026; the console's money figures moved to TB5 with switching on; the tax rates as dated rows moved from TB4 to TB2, since a quote needs them; plans.html, which no slice named, was built with TB2, where paying starts), each with its tests, docs and a journey chapter. Built in Atrium; Desk's M18b is read and
   rewritten, never shared (it runs on Desk's own tenancy and has no products). Billing stays off as shipped (TB-2): every
   product is complimentary until its switch is turned on.

### 6.1 · Slices

| Slice | What | Done when |
|---|---|---|
| TB1 ☑ | **The catalogue as data, and complimentary by default.** An offering's monthly and yearly price, what it allows (limits) and what it includes (features), as rows; an agreed price for one organisation until a date (TB-1, TB-4). Each product's billing state, *complimentary* as shipped (TB-13), and each organisation's own terms per product: as the product, charged from today, complimentary for good, with "agreed with" and an audit line (TB-16). Free renews itself (TB-8). Products hear what an organisation holds and allows, by webhook and `GET /v1/entitlement`, and report the counts they keep against the limits. The console's Billing: offerings and money, an offering beside its preview, an agreed price, billing for one organisation | `console.html`'s offerings, offering, agreed and one-organisation states, by test; a Free entitlement rolls on by itself; a product reads its limits and reports its counts |
| TB2 ☑ | **Paying.** Paystack behind a gateway with a `log` driver for development (IA §6: the hosted page, no script on `id`). Checkout for a plan, monthly or yearly, by card or mobile money; back from Paystack, the webhook with its signature, and a scheduled check, settling each payment once. A paid period per payment. Moving up at once with the unused days credited before tax, down at the next period (TB-12). The billing role's permissions at `id`, and the billing-only view (CL-16) | `pay.html`, every state, by test, with the `log` driver; a payment settled by return and webhook together counts once |
| TB3 ☑ | **Renewals and lapses.** A card renews itself from Paystack's saved authorization, by Atrium's scheduler; mobile money is reminded 14, 7 and 1 days before (TB-9); a failed renewal retries, then the grace days (TB-11), then Free (TB-3), nothing deleted; an organisation charged from today gets the grace days to choose. Never while Atrium was down (the failsafe). The organisation's Billing page with the year as a ribbon | `subscription.html`, every state, by test, on a frozen clock |
| TB4 ☑ | **Tax invoices and receipts.** NHIL, GETFund and VAT as dated rates on their own lines (TB-5); numbered at payment, cleared through E-VAT by a queued job behind a driver (`log` for development), a receipt until cleared, retried and the Service told (TB-14); the PDF with the GRA's mark and QR. Withholding: paying net, the certificate within 30 days, the Service told when it lapses (TB-15) | `invoice.html`, every state, by test; an invoice keeps the rates it was issued under |
| TB5 ☑ | **Switching billing on for a product** (TB-13): blocked until prices, the VAT registration, E-VAT, Paystack and the terms are in place; the announcement e-mail, at least 60 days' notice, the founding price, organisations on their own terms kept. The console's money figures | `console.html`'s switch state, by test; organisations are told once, and nothing is charged before the date |
| TB6 ☑ | **Docs and a review of the money paths**: the manual, reference, map and journey; a security review of the webhook, the gateway and the invoices | Each document is updated, and the review is written |

**TB3, built 8 November 2026.** As the slice says, with these settled in the building: the reminder days, the tries for a card and the days between them are settings (`subscription.reminder_days` 14, 7, 1; `subscription.renewal_tries` 2; `subscription.retry_days` 2, from the mockup's 6 and 8 November); the grace days count from the day Atrium tells the organisation, which is how "never while Atrium was down" is kept; a period paid by hand can be paid ahead from the first reminder, and through the grace days, carrying on from where the last ended; a period paid after it lapsed starts on the day; Free chosen for the next period happens without telling anyone; and products are told `grace_until` with the entitlement. The Billing page's "Change" card button became a line: Paystack keeps a card only when one pays, so the next card paid with replaces it.

**TB4, built 8 November 2026.** As the slice says, with these settled in the building: the GRA's E-VAT driver refuses until the GRA's access and specification come (the request is written from the specification, not guessed), so every invoice is a receipt until then; withholding is worked on the price after any credit and before tax, as the mockup does, with tax-ghana.md's question still open; withholding tax is offered only on a price over GH₵ 2,000 (`over` on its rate); sending a paper to someone mails a signed link to its PDF for 30 days, not an attachment; a year downloads as a spreadsheet. The paper is a component (`InvoicePaper`), as the order's ticket is. The monthly report for the VAT return isn't built: it belongs with TB5's money figures.

**TB5, built 8 November 2026.** As the slice says, with these settled in the building: "fees may first apply … at each renewal" means an organisation on a paid plan given complimentary keeps it to the end of its term, and everyone else gets the grace days after the day to choose (`Billing::chooseBy`); the founding price belongs to organisations holding the product on the announcement day, and goes once a paid period of theirs lapses; the public terms are confirmed on the form, since they live outside Atrium; a launch can be called off before its day (the organisations were told, so the Service tells them). The monthly figures for the VAT return aren't built: the console shows the money Atrium holds, and a return report waits for E-VAT's real numbers.

**TB6, built 8 November 2026.** The money paths were reviewed by a reader who hadn't written them, each finding checked against the code;
`reji/docs/SECURITY_REVIEW_TABULA.md` scores them 7.4 of 10, ready for staging on Paystack's test keys and not yet for live money. One serious
fault (an unclear card renewal charged twice) and four lesser ones were fixed with tests (`MoneyPathsTest`). Left for the Architect to
schedule: refunds, chargebacks and credit notes (Priority 1), and a Service review of withholding certificates with a balance due (Priority 2).

## 7 · Money back: refunds, credit notes and chargebacks

Priority 1 of the TB6 review. Opened by the Architect on 8 November 2026 ("Money back first"); part of Tabula rather than a
module of its own, since it uses Tabula's payments, webhook, invoice numbering and E-VAT driver.

### 7.0 · What it is, what it covers, and how things carry on without it

**In simple terms.** Giving money back cleanly, in both directions. **A refund the Service gives**: an amount and what happens
to the plan; Paystack returns the money to the card or wallet; once it has gone, Atrium issues a **credit note** against the
invoice, cleared through E-VAT as invoices are. **A chargeback the school's bank starts**: Atrium records it, tells the Service
when the answer is due, and lets it defend or accept; if the bank finds for the school, the period that payment bought ends and
the organisation moves to Free, with nothing deleted.

| Atrium (Tabula) handles | The product handles |
|---|---|
| Refunds, whole or part, started by the Service; never more than what's left unrefunded | Nothing new: it hears of a changed plan as it hears of any change of plan |
| Paystack's refund call and its events (pending, processing, processed, failed, needs-attention) | Enforcing what it's told |
| Credit notes: their own numbers, the invoice they refer to, VAT reversed on separate lines, cleared through E-VAT | · |
| Disputes: recorded on the payment, the deadline, the reply, the outcome and what it does to the plan | · |
| Telling the Service and the organisation | · |
| The payments TB6 keeps aside (`billing.payment_unapplied`), refunded with one action instead of by hand | · |

Not in it: money a product collects from its own customers (Aerarium), SMS credit wallets (TB-6), and the Service's review of
withholding certificates (Priority 2, its own discussion).

| What stops if Atrium is down | What carries on |
|---|---|
| Starting a refund or answering a dispute from the console | Paystack's dashboard is the fallback for both. A refund made there, or a dispute settled there, still reaches Atrium as an event; a refund Atrium didn't start is recorded as *keep the plan*, and the Service is asked whether the plan should change |
| Paystack's refund and dispute events can't reach us | Paystack retries, and a daily check asks Paystack about every refund still open and every open dispute, so none is missed |
| Paystack's refund call fails | The refund stays *asked* and a job tries again; nothing else changes until Paystack confirms |
| E-VAT is down | The credit note is numbered and cleared later, as invoices are (TB-14) |
| A dispute's deadline falls in the outage | The deadline is Paystack's; Paystack reminds every 4 hours, and the Service can answer in Paystack's dashboard |

### 7.1 · Decisions

**Decided by the Architect, 8 November 2026: TB-17 to TB-22, as recommended.**

| # | Decision | Recommended (decided) | Alternative |
|---|---|---|---|
| **TB-17** | Who starts a refund | **The Service only**, from the console, with the password and a reason. The reasons are Input Fields (the house rule on lists). A school asks through support | Schools request a refund at `id` and the Service approves it: a request queue not needed yet |
| **TB-18** | What a refund does to the plan | **The Service chooses each time, from three**: *Keep the plan* (goodwill, or an overcharge); *End the period now* (Free from today, the unused days suggested as the amount); *Undo the payment* (the period never existed: for mistakes and TB6's set-aside payments). The amount is suggested from the choice and can only be lowered. The three are code, not Input Fields: each changes what Atrium does | Refund whole payments only and always end the period: can't do a partial goodwill refund |
| **TB-19** | How the amount is suggested | **The unused days pro rata, or the whole payment within a window**: a setting, 14 days to start. The Service decides; the public terms state the policy | No suggestion: every amount worked out by hand |
| **TB-20** | When a credit note is issued | **When Paystack confirms the money went** (`refund.processed`), numbered `CN-YYYY-NNNN` from its own gapless count, referring to the invoice (or the receipt while E-VAT is pending), with the tax reversed in proportion, line by line | When the Service asks: a refund that then fails leaves a credit note standing, and undoing it takes a debit note |
| **TB-21** | A mobile-money refund Paystack can't complete | **The Service records the payout made by hand** (the wallet, the transaction ID, the date) and marks it sent; the credit note follows, so the books stay whole | Mobile money refunded outside Atrium altogether: invoices left standing for money already returned |
| **TB-22** | A chargeback | **The plan keeps running while it's open** (banks take weeks). The Service is told at once and sees the deadline; the console gathers the evidence (the payment, the invoice, who paid and from where); the Service defends or accepts. **If lost**: the period ends, Free, a credit note, the owners told, the saved card dropped (they can pay again another way). The organisation hears only the outcome, not the dispute | Suspend the plan while a dispute is open: punishes a school for its bank's process, which may be the bank's mistake |

### 7.2 · Facts only the Architect has

None blocks building; all come before live money.

- The refund policy in the public terms (TB-19's window follows it).
- Whether Tutelora's Paystack account in Ghana refunds mobile money by itself (Paystack's support can say; it varies by provider).
- The accountant's view of a credit note on an invoice paid net of withholding (the mockups refund what was paid and reverse the
  tax in full, with the withheld share shown as its own line).
- The GRA's specification for credit notes, which comes with E-VAT access.

Paystack's documentation refused automated reading on 8 November; its refund and dispute behaviour above is from its own pages and
support articles as found by search. Every endpoint and event is checked against its API reference with test keys before TB7.

### 7.3 · Mockups (`reji/ui/html/tb/moneyback.html`)

One file, by the same `build-mockups.py`: in the console, the payment's drawer with **Give money back** (the three choices as
cards, the amount with its unit, the reason, the password); **Money back** in the console's Billing (refunds under way, disputes
counting down, set-aside payments); a refund that **needs the payer's details** (the payout recorded by hand); a **dispute**
drawer (the deadline as a ring, the evidence gathered, Defend or Accept) and a **dispute lost**; at `id`, an invoice with its
**credit note** beneath it and the **credit note** itself; the e-mails; the phone. Light and dark from the page's own switch.

**Drawn 8 November 2026** and checked in every state, light, dark and on a phone. The picture: each refund on its way home as a
track (asked, with Paystack, sent back, a credit note, cleared by the GRA); a chargeback as a clock; the period as the days used and
the days coming back. Choices the mockups make, for the Architect to confirm or change: the networks a payout is sent from are Input
Fields; a lost chargeback's credit note is for the whole payment, as the bank returns it all; the organisation is told of a refund only
once the money has gone; a refund made in Paystack's dashboard gets a credit note at once, as *keep the plan*, until the Service
chooses otherwise; amounts and names are examples.

### 7.4 · Slices

| Slice | What | Done when |
|---|---|---|
| TB7 ☑ | **Refunds.** Paystack's refund call behind the gateway (the `log` driver for development), its events by webhook and the daily check, each settled once; a refund's states; the three effects on the plan (TB-18) and the suggested amount (TB-19, its setting); the reasons as Input Fields; a payout recorded by hand (TB-21); a refund made in Paystack's dashboard recorded and asked about; TB6's set-aside payments refunded in one action. The console's **Money back** and the payment's drawer; the organisation told | `moneyback.html`'s refund states, by test; a refund confirmed by return and webhook together counts once; never more than what's left |
| TB8 ☑ | **Credit notes.** Their own gapless count (`CN-YYYY-NNNN`), issued on `refund.processed` or the payout recorded, kept as issued with the parties and the rates of the invoice they refer to; cleared through E-VAT by the same queued job (TB-14); the PDF; listed under the invoice at `id` and in the year's spreadsheet | `moneyback.html`'s credit-note states, by test; a credit note keeps its invoice's rates |
| TB9 ☑ | **Disputes**, and the review again. Paystack's dispute events and the daily check; a dispute on its payment with its deadline; the evidence gathered; Defend (with the evidence) or Accept from the console, or the outcome followed from Paystack's dashboard; lost: the period ends, Free, a credit note, the saved card dropped, the owners told (TB-22). The money paths reviewed again, the score updated | `moneyback.html`'s dispute states, by test; Priority 1 of the review closed |

**TB7, built 8 November 2026.** As the slice says, with these settled in the building: the effect on the plan lands when the Service
asks, under a lock on the payment, not when Paystack confirms (a school that asked to leave isn't kept waiting on a bank; a refund that
then fails keeps its money in the Paystack balance, and the Service sends it by hand or asks again under a new reference); undoing a move
up, or a period paid ahead, puts back the period it replaced or renewed when that still runs; ending a period not yet started undoes it.
The password is the console's step-up dialog, as every billing write's, not a field in the drawer. The track has three steps (asked, with
Paystack, sent back) until TB8 adds the credit note and the GRA. The networks a payout is sent by are Input Fields (`payout_channel`), and
giving money back is its own permission (`refund.manage`), apart from changing offerings. A payment is found to give money back on under
Paid lately, by an organisation's name or a payment's reference. Fixed on the way: the console's drawers sat above dialogs and pickers,
so a picker's list and the password dialog opened behind a drawer; drawers now sit over the shell and under what opens over them.

**TB8, built 8 November 2026.** As the slice says, with these settled in the building: a credit note is a row of `billing_invoice` of its
own `kind`, so it goes through the same E-VAT job, hourly run, Service alert, PDF, pages and spreadsheet as an invoice; its count is apart
(`CN-…`). It names the invoice it adjusts and the refund it records, carries that invoice's parties, and keeps its own lines as issued. For
a school that paid net of withholding it credits the refund plus the school's share of what it withheld, shown on its own line, so what
went back is the refund exactly (the accountant's view is still open, §7.2). The invoice at `id` gets the banner with the refund's track,
a *Refunded* or *Part refunded* stamp and its credit notes beneath; the refund e-mail names the credit note. Refunds processed before TB8
(the local demo's) were given theirs by hand.

**TB9, built 8 November 2026.** As the slice says, with these settled in the building. Paystack gives **16 hours** to answer a dispute,
not the days the mockup drew, and accepts it by itself after; the clock counts those hours, and a dispute left to run out is lost the same
way as one accepted. Defending needs a receipt uploaded to Paystack: the payment's invoice as a PDF goes, so a payment with no invoice can
only be accepted. The money a lost dispute took back is recorded as a refund of its own (`origin` dispute), which ends the period while it
runs (or keeps the plan when that period was already over, as when the disputed payment's plan had been moved up from) and gets a credit
note; it isn't told as a refund. The organisation's e-mail says what became of its plan. The second review (`SECURITY_REVIEW_TABULA.md` §8,
7.7 of 10) found three serious faults and three lesser, all fixed with tests (`MoneyBackReviewTest`): a refund is now refused while a bank
disputes the payment, and Paystack's dispute outcomes are read only from its explicit resolution, to be confirmed with test keys.

## 8 · Withholding's review step (TB10)

The TB6 review's Priority 2 (withholding scored 5 of 10). **Decided under the Architect's autonomy grant, 8 November 2026** (master plan §3):
the Architect handed over the order and the decisions, so TB-23 to TB-25 below are mine, taken as recommended and written here to be
reviewed afterwards.

### 8.0 · What it is, what it covers, and how things carry on without it

**In simple terms.** Since TB4 a school may pay net of withholding tax and send the GRA's certificate within 30 days; Atrium keeps the file
and tells the Service, but nobody checks it, and nothing happens if it never comes. TB10 closes that: the Service reads each certificate and
accepts or rejects it; a rejected one, or none by its day, leaves the withheld amount as a balance the organisation pays at `id` (or settles
with a corrected certificate); and an organisation that owes one can't pay net again until it's settled. The plan is never taken away for
the paperwork (TB-15 stands).

| Atrium (Tabula) handles | The product handles |
|---|---|
| The review in the console: the certificate, the figures it should show, accept or reject with a reason (Input Fields) | Nothing |
| A balance due: the withheld amount, paid by card or mobile money through Paystack at `id`, or settled by a corrected certificate | Nothing |
| Telling the organisation when a certificate is rejected or overdue, once each | Nothing |
| Not offering withholding to an organisation that owes a balance | Nothing |

| What stops if Atrium is down | What carries on |
|---|---|
| Reviewing, paying a balance | Everything else: the plan runs, as it always does while a certificate is open; a balance payment settles by return, webhook or check like any payment |

### 8.1 · Decisions (decided under the autonomy grant)

| # | Decision | Taken | Alternative |
|---|---|---|---|
| **TB-23** | Who checks a certificate | **The Service, in the console**, accepting it or rejecting it with a reason (`certificate_reject_reason`, Input Fields: unreadable, wrong amount, names someone else, not the GRA's, other), its own permission (`certificate.review`), the password again. Accepted settles the withheld part | Trust every upload: what TB4 did, and why withholding scored 5 |
| **TB-24** | What a rejected certificate, or none by its day, leads to | **A balance due**: the withheld amount, which the owners and billing people pay at `id` by card or mobile money (no tax on it: it's the rest of an invoice already issued), or settle with a corrected certificate. Told once each. The plan is never taken away (TB-15) | Take the plan back to Free until paid: holds a school's product hostage to paperwork, which TB-15 refused |
| **TB-25** | Paying net again while a balance is owed | **Not offered** until it's settled: the pay page says why | A per-organisation switch for withholding agents, set by the Service. Left for later: the balance rule covers the abuse, and nothing yet says which schools are agents |

### 8.2 · Mockups (`reji/ui/html/tb/withholding.html`)

In the console, **Withholding certificates**: to review, balance due, waiting, settled; a **certificate's drawer** with the file, what it
should show and accept or reject. At `id`, the invoice with a **balance due** (rejected, with the reason; or overdue), **paying the balance**,
and **settled**. Light, dark and the phone. Drawn and checked 8 November 2026.

### 8.3 · The slice

| Slice | What | Done when |
|---|---|---|
| TB10 ☑ | The review (TB-23), the balance due and paying it (TB-24), withholding withheld from an organisation that owes (TB-25), the e-mails, the console page and drawer, the invoice page's states, and the review's score again | `withholding.html`'s states by test; a balance settles once; withholding refused while one is owed |

**TB10, built 8 November 2026** (under the autonomy grant). As the slice says, with these settled in the building: a balance is a payment of
its own purpose (`balance`) that settles its withholding instead of starting a period or issuing an invoice, and one paid after the
withholding was settled another way is kept and refunded, as a stale quote is. A corrected certificate comes back to review. The pay page
opens without withholding while one is owed, and says why. Local demo: the review can't be tried with a real upload here (`FILE_VAULT_KEY`
isn't set locally), so the overdue state was set by hand and its balance paid through the development checkout. The review's withholding
section now scores 7 of 10, and the money paths 8.0 overall.
