Branch session
A branch session is the umbrella record for a single trading day at a single branch. Open it in the morning before tellers can transact, close it in the evening only after every till and the vault are reconciled. It is the unit of cash GL cut-off.
What a branch session represents
The branch session (`mfi.branch.session`) is created once per branch per trading day. It links the day's vault session and all till sessions, holds the open / close timestamps, and posts the closing GL cut-off journal that locks the day's cash position. Without an open branch session, no till can open and no cash transaction can post.
Opening the branch
- Branch manager (or delegated supervisor) opens the day from MFI → Cash → Branch Session → New.
- System checks: previous day's session is closed; if not, blocked.
- System checks: no orphan till sessions; if any, blocked.
- Manager confirms opening cash declared (matches yesterday's closing).
- System opens a vault session for the day (still requires dual-control swipes).
- Branch session is now OPEN; tellers can request till float draws.
- Public opens to customers when first till is active.
During the day
While the branch session is open, the system tracks live aggregates: total cash-in, total cash-out, count of till sessions opened, mid-day sweeps, current vault and till balances, pending incidents. The branch manager can pull a snapshot at any time from the session form.
- Live position rolls up till + vault denomination ledger
- All till sessions and the vault session are children of the branch session
- Cash policy is resolved at session open and frozen for the day — a policy change mid-day applies tomorrow
Closing the branch
- Public counter closes at advertised time (typically 17:00).
- Tellers run their till close (denomination count, reconcile, variance handling).
- After every till session is closed_clean or closed_with_variance, vault is counted.
- Vault session closes (dual control).
- Branch manager runs the End-of-Day wizard from the branch session.
- Wizard validates: no open till sessions, no open variance incidents above branch cap, vault overnight balance within policy.
- If overnight balance breaches max: requires regional override or CIT off-load.
- Manager signs off electronically.
- System posts cash GL cut-off journal: closes each cash account at its closing balance.
- Branch session moves to CLOSED state.
GL cut-off mechanics
At branch close, the system posts a cut-off journal that:
- Closes every till GL account back to zero (because cash returned to vault)
- Confirms vault GL account balance equals physical vault count
- Triggers M-Pesa / bank account reconciliation snapshots
- Stamps the period such that subsequent retro-postings to today are blocked at this branch (requires reopen authorisation)
Exception: branch did not open
If a branch did not open (public holiday, security alert, manager unavailable), no branch session is created and no daily cut-off is posted for that branch. The next-day session opens against the carry-forward vault count from the last open day.
HQ / Treasury session
HQ Treasury runs its own daily session for the central vault. It follows the same controls but with elevated authoriser caps and an additional CIT-summary section showing all in-transit trips that touched HQ today.
Worked scenarios
Scenario — Closing Karen branch after a busy month-end Friday
| Character | Role |
|---|---|
| Florence Achieng | Branch manager |
| Peter Otieno | Supervisor |
| Aisha Hassan | Regional manager |
Timeline
- 16:55: Florence locks the public door. Three tellers begin individual till close. (Branch session still OPEN)
- 17:20: Tellers complete clean closes. One had a KES 150 shortage — accepted at supervisor cap with incident. (All till sessions CLOSED)
- 17:25: Florence and Peter run vault count. Total KES 6,200,000. Above KES 5M overnight max because of month-end disbursements queued for Monday. (Vault overnight max breach)
- 17:28: Florence calls Aisha for regional override. (—)
- 17:32: Aisha logs in remotely, reviews context, electronically authorises overnight excess up to KES 7M for tonight only. Insurance underwriter cc'd by automation. (Override granted, branch can close)
- 17:35: Florence runs the EOD wizard. All checks pass with the override. (EOD WIZARD PASSED)
- 17:36: Florence signs off. System posts cut-off journal. (Branch session CLOSED)
- 17:38: Aisha schedules an emergency Saturday CIT pickup for Monday's disbursement pre-funding. (CIT trip scheduled)
Outcome — Branch closed legally with documented regional override; emergency CIT scheduled; incident on KES 150 shortage stays open for officer follow-up.
Reference
Branch session states
| State | Meaning |
|---|---|
| draft | Created but vault not yet open |
| open | Vault open, tills can transact |
| closing | EOD wizard in progress |
| closed_clean | Closed within all policy limits |
| closed_with_override | Closed via documented override |
| reopened | Reopened after close for correction (requires authorisation) |
EOD wizard checks
| Check | Block / Warn | Bypass authoriser |
|---|---|---|
| All till sessions closed | Block | Branch manager (force close) |
| No open level-3 incidents | Block | Regional manager |
| No open level-2 incidents > KES 50k | Block | Regional manager |
| Vault overnight within policy | Block | Regional manager |
| Insurance cap not breached | Warn | Head of treasury |
| Pending CIT outbound completed or rolled | Warn | Branch manager |
| KRA ETIMS submissions in sync | Warn | Branch manager |
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Cannot open today's branch session — 'previous day not closed' | Yesterday's session was never finalised | Open yesterday's session, run the EOD wizard with the actual yesterday-evening counts, sign off, then today opens. |
| EOD wizard blocked by an incident the branch resolved on paper | Incident record not updated to closed | Open the incident, complete the close-out fields, attach the resolution document, sign off. EOD then proceeds. |
| Cut-off journal posted to wrong period | Branch system clock skew | Verify branch server NTP is in sync. Re-post the cut-off journal manually to correct period; document via change ticket. |
| Reopened session cannot be re-closed — 'fields changed' | Cash policy was updated between original close and reopen | Restore the original policy version at the session, re-run the EOD checks, close. Then revert policy. |
| Branch session shows different total than the Treasury dashboard | Dashboard cache out of sync; usually 60-second lag | Trigger a manual sync from Treasury → Refresh, or wait for the next minute. If persistent, check the cash_dashboard cron. |