# Money and the books — the handbook

## From a card payment to the books (every sale)
1. The guest/agent/corporate pays by card through the payment gateway. The server works out the amount itself (a page can never pay less) and checks it to the cent.
2. Only after a successful payment is the booking saved. A successful payment is never overwritten.
3. The booking gets a tax invoice number (INV-YYYY-NNNNN, one sequence, no gaps — a gap is recorded as void).
4. **Ledger lines** are written for the booking. They always add back exactly to the sale:
   - `sale` — what the customer paid (gross)
   - `cost` / `supplier_payable` — owed to the supplier(s) (net cost for packages)
   - `processing` — the gateway fee (a cost)
   - `card_fee`, `corp_fee` — fees charged on top (card fee, corporate service fee)
   - `vat` — VAT for SARS (on our part only for live sales; principal VAT on our own packages)
   - `live_share`, `seller`, `introducer`, `payout` — agents' money
   - `getaway`, `api` — the owners' shares
   - `addons` — live add-ons inside a package
5. A **VAT register** line is written once per sale, dated the sale day in South African time.
6. Lines are `pending` until the trip is travelled, then `earned`. Agents are paid on travel, not on booking.

## Worked examples — HISTORIC (settings of 15 Nov 2026 before the owner's change: flights were R250 fixed, no card fee)
Settings change. For TODAY's figures always use LIVE DATA ("What a usual sale of each kind pays us now") and the ADVISOR lines —
never these. Since 15 Nov 22:05 flights are 10% and customers pay a 1% card fee. The examples only show HOW the split works:
- **Hotel, supplier R5 000** → customer pays R5 575.00 → supplier R5 000.00, gateway R163.68, VAT R75.00, Getaway R168.16, API R168.16. Platform keeps R336.32.
- **Local flight, supplier R3 000** → customer pays R3 287.50 → supplier R3 000, gateway R97.34, VAT R37.50, Getaway R76.33, API R76.33. Platform keeps R152.66.
- **International flight, supplier R3 000** (our fee zero-rated) → customer pays R3 250 → gateway R96.25, Getaway R76.88, API R76.87. Platform keeps R153.75.
- **Car hire, supplier R3 000** → customer R3 345 → gateway R99.01, VAT R45, Getaway R100.50, API R100.49.
- **Coach, supplier R600** → customer R655.20 → gateway R21, VAT R7.20, Getaway R13.50, API R13.50.
- **Our own package "Cape Town & Winelands Explorer"** R12 500, net cost R10 000 → gateway R364.50, VAT R326.08, Getaway R1 266.59 (70%), API R542.83 (30%). Platform keeps R1 809.42.
If settings change, these change for NEW sales only — always check the live example on Fees & margins.

## Month-end close (do it in this order, after the month has ended in SA time)
1. **Dashboard → Needs you**: clear every red money check first (payments without bookings, cancelled bookings still holding money, mismatches).
2. **Finance → Platform → Reconciliation**: every card payment matched to a booking, every booking to its ledger.
3. **Finance → Agents → Statements & payouts**: run the month. Each agent gets statement ST-YYYYMM-id with every earned, travelled line. A month where fees exceed earnings is carried forward. Agents may query within 30 days; answer the query; then mark paid with the EFT reference.
4. **Finance → Platform → Suppliers**: record what was paid to each supplier with the bank reference.
5. **Finance → Platform → VAT**: the VAT for the month from the register (output less claimable input). Record the SARS payment with its reference. Collect suppliers' and VAT-registered agents' tax invoices for any input VAT still flagged.
6. **Finance → Platform → What we owe**: the owners' settlement — record what API paid Getaway (or the other way) with the reference.
7. **Finance → Corporates → Monthly fees**: mark each corporate monthly fee paid when the EFT arrives.
8. Optional: **Finance → Books** → export the journal for the accountant; check 9999 Suspense is nil.

## Refunds and cancellations
- Cancelling a paid booking makes a refund due (dashboard reminds you).
- Record the refund ONCE (cannot be changed): amount back, what the supplier keeps, the bank/gateway reference. The system writes separate ledger lines for what went back and what was kept (`cancel_*`), issues a **credit note** (CN-YYYY-NNNNN) — the original tax invoice is never altered — and writes the VAT credit dated the refund day.
- The gateway's fee on the original payment normally stays a cost to us.
- A chargeback is recorded the same way (kind chargeback).
- Agents' commission on a cancelled booking is reversed.

## The general ledger (Finance → Books)
Double-entry, built automatically from ledger lines, receipts and payments:
- 1000 Bank = the cash position on the Reconciliation
- 1100 Customers = still owed on deposits − refunds still due
- 2100 Suppliers = owed to suppliers − paid to them
- 2200 Agents = earned (less monthly fees) − statements paid
- 2300 VAT = VAT collected for SARS − VAT paid
- 2400 Gateway = always nil (the gateway takes its fee at source)
- 9999 Suspense = must be nil (money with no booking)
Debits always equal credits.

## How we know the books are right
- `tools/books-proof.php` — 53 identities (every rand accounted for) on a copy of the database. Last run 15 Nov 2026: all hold.
- `tools/backoffice-audit.php` — 522 automated checks of the whole system (15 Nov 2026: all pass).
- `tools/ledger-fuzz.php` (5 331 checks) and `tools/books-fuzz.php` (1 314 checks) throw random sales, refunds and payouts at the engine.
- The books check (`gw_integrity_issues`) runs daily and inside the dashboard's money checks.

## Rules a bookkeeper would insist on (all enforced)
- Records kept at least 5 years (monthly backups kept 6 years).
- Nothing deleted: people, packages and bookings with money history are suspended or taken off sale, never deleted.
- After go-live the database itself refuses changes to sealed records (triggers) and the audit log is sealed.
- Every money setting change is in the audit log with old → new values.
