Apache Fineract teller and cashier management: when branches need it and what it changes
A branch-based lender or cooperative that takes cash over the counter needs to know, at the end of each day, where every shilling, dollar or peso went and whether it matches the ledger. Fineract's teller and cashier features give each branch a structured record of tellers, the cashiers assigned to them, and the cash allocated to and settled from each cashier, so cash movements are captured in the core system instead of only in spreadsheets. Teams implement this module when branch volumes make manual cash logs unreliable, when several cashiers share a till, or when cash movements must be traceable to a named person and a date. Confirm the exact teller, cashier and settlement screens and endpoints against the Apache Fineract platform documentation for the release you plan to run, since the workflow is only as useful as the version you deploy.
The scope boundary matters before any design starts. Fineract records the teller and cashier entities and the cash movement workflow, but it does not run your physical cash control. Vault policy, dual control on cash counts, limits per cashier, how shortages and overages are investigated, and who signs off the daily reconciliation are decisions your finance and risk functions must make and document. Fineract can hold the evidence of those steps, but the policy itself lives in your procedures and your people, and an auditor will test the procedures as well as the records.
Fineract is headless and provides no user interface of its own, so the branch front end where cashiers open a drawer, record a cash receipt or request a settlement must be built or chosen separately. The project's README points to the Mifos X web application as a front end used in its Kubernetes example, but confirm whether it covers your teller workflow before assuming it does. Plan the front end, its authentication and the roles each cashier and supervisor holds as part of the same design, because the permissions you grant in the API determine what a branch user can actually do.
What the teller module does in Fineract
The teller module models branch cash as a chain of hand-overs: from teller to cashier, then settlement back to the teller. Each step is tied to a named office, a dated assignment and, where the documentation describes it, a journal effect. Confirm exact endpoints and statuses against the 1.15.0 documentation before you write procedures or test cases.
Tellers defined per office
A teller is the cash point that belongs to a branch office in Fineract, so the teller structure follows the office hierarchy you designed earlier. Decide how many tellers each office needs and who owns each one, because that ownership determines which cash drawers and daily sessions can be opened in a branch. Confirm in the 1.15.0 docs how teller records are created, edited and deactivated, and whether a teller can be closed while cash is still assigned to it.
Cashier assignment for the day
A cashier is a staff member assigned to a teller for a given business day, which gives that day's cash transactions a named owner. Plan for shift changes, absences and staff who cover more than one teller, since each assignment ties cash handling to a person. Confirm how assignments are dated, whether one cashier can hold two active assignments, and what happens to open assignments at the end of the day.
Allocating cash to cashiers
Allocation records the opening float or additional cash handed from the teller to a cashier before transactions begin. Treat the allocated amount as the control figure for the cashier's drawer, so a later mismatch can be traced to a specific hand-over. Confirm which currency and denomination details the allocation captures, and whether allocation is possible only on an open teller with an active cashier assignment.
Settling cash from cashiers
Settlement closes a cashier's cash position at the end of a session by recording what was returned to the teller against what the system expects. Variances need an agreed procedure covering who approves them, where they are booked and how they are cleared. Confirm the settlement statuses, any approval step, and whether a settlement can be reversed or corrected after the teller is closed.
Journal effects of cash movements
Cash movements between the vault, teller, cashier and branch accounts are expected to produce journal entries, so the teller module belongs in your accounting design alongside the ledger mapping. Map each movement to the cash and clearing accounts agreed with finance before go-live. Confirm in the 1.15.0 docs which events create journal entries, when they post, and how a day's cash movements reconcile to general ledger balances.
How cash moves from vault to teller to cashier and back
Branch cash should move in one fixed order: the vault (or head cashier) holds the branch's physical cash, allocates a float to each cashier at the start of the day, the cashier transacts with customers, and the cashier settles back to the vault at close. Each handover transfers responsibility as well as money, so the record of every step must show who held the cash and how much. In Fineract terms, the teller is the branch cash point, the cashier is the individual drawer assigned to it, and the allocation and settlement records are the handovers the ledger must be able to match. If the sequence breaks, for example when a settlement is entered before the day's transactions are final, the expected balance and the counted cash diverge, and the difference becomes hard to trace.
Each step needs its own accounting event. Allocation should move value from the vault's cash account to the cashier's cash account, so the drawer is visible on the ledger before any customer transaction happens. Customer transactions at the cashier should post to the client's savings or loan account and to that cashier's cash account, so the drawer balance equals its activity. Settlement reverses the allocation, and any surplus or shortage goes to a dedicated difference account where it stays visible for review. Reconciliation works backward from the vault: opening float, plus cash received, minus cash paid out, should equal counted cash, and any gap must trace to a specific handover or transaction. Confirm that your chart of accounts maps each of these accounts before go-live.
Before the build, decide who holds the vault role, whether one cashier can hold more than one drawer in a day, the cut-off time for settlement, and who approves a shortage. Then confirm, in the release you plan to run, which allocation and settlement actions post journal entries automatically, which accounts they hit, and whether the teller reports list cash movements in a form your branch controllers can reconcile against the general ledger. Test each path with a closing day that includes a deliberate shortage and a reversed transaction. Check the exact behavior against the Apache Fineract platform documentation for your release, since teller behavior depends on configuration in each deployment.
Configuration decisions for tellers and cashiers
This table compares the main design choices for branch cash handling in Fineract, with the options for each, when they fit, and what to confirm in the vendor documentation before configuring anything. Read each row as a decision to settle with operations and finance before the build starts, since most of them are hard to change once transactions are posted.
| Decision | Options | When each fits | What to confirm |
|---|---|---|---|
| Tellers per branch | One shared teller per branch, or several tellers per branch each tied to a cash drawer | One teller suits a small branch with one counter. Several tellers suit branches where staff handle cash in parallel and need separate balances. | Whether teller records are scoped to an office, and how a teller maps to a staff member and a cash location |
| Cashier assignment period | Cashiers assigned per day, or per shift within a day | Per-day assignment suits branches with fixed staffing. Per-shift assignment suits branches with two or more cash handovers in a business day. | Whether cashier allocations can span several days and how a cashier's open allocation is closed at end of day |
| Who may allocate and settle cash | Branch supervisor only, or teller and supervisor roles with separate permissions | A supervisor-only model fits high-value branches with strict dual control. Split permissions fit larger branches where tellers handle their own drawers. | Which permission codes govern allocation, settlement and reversal, and whether they can be separated by role in your setup |
| Partial settlement | Settle the full cashier balance at once, or allow partial settlements during the day | Full settlement fits branches that close drawers once daily. Partial settlement fits branches that move cash to a vault during peak hours. | Whether a cashier balance can be settled in several entries and how each partial settlement posts to the ledger |
| Handling cash differences | Record the variance as a cash-over or cash-short entry, or require supervisor approval before settlement closes | Approval before close fits controlled branches with audit requirements. Recording the variance directly fits low-value branches with agreed tolerances. | Which accounts receive variances, whether an approval step exists in the release you run, and how variances are reported |
| Currencies in scope | Single base currency, or several currencies with separate cash balances per currency | A single currency fits domestic branches. Multiple currencies fit border or remittance branches that hold foreign notes. | How currency codes are configured per cashier allocation and whether exchange gains or losses post automatically |
| Ledger reconciliation point | Reconcile at each settlement, or reconcile once at end of business day | Per-settlement reconciliation fits branches with frequent vault movements. End-of-day reconciliation fits branches with few movements. | Which journal entries each teller and cashier action creates and when those entries appear in the general ledger |
Implementation sequence for teller and cashier setup
This sequence turns branch cash handling into a tested configuration that matches how your branches actually move cash. Each step produces a written output that the next step depends on, so gaps surface before live branch days begin.
Confirm office and staff structure
Start by fixing the office hierarchy, the staff records and the reporting lines that tellers and cashiers will sit under. Your operations lead and the branch managers confirm which offices hold cash, which staff handle it, and who approves a cash settlement. The output is a signed-off office and staff map that lists every teller location and every person who may act as a cashier, with their approving manager. Do not move on until the map matches the current organization chart.
Define teller and cashier roles and permissions
Translate the cash handling duties into Fineract roles and permissions, separating the people who receive cash, the people who approve allocations and the people who settle cashier balances. Your security lead reviews the role matrix against your segregation of duties policy and checks it with the platform's permission model in a test tenant. The output is an approved role matrix with one named owner per permission, plus a list of any duty you cannot separate and the compensating control for it.
Design the general ledger mapping for cash accounts
Map every cash movement type to a general ledger account before any teller is configured, covering vault or teller cash, cashier allocations, cash in transit and any short or over difference. Your finance team and the accounting lead agree the mapping with the chart of accounts and confirm how each movement posts, including the offices and currencies involved. The output is a mapping sheet that a reviewer can trace from each branch transaction to its journal entry. Check it against the accounting settings in your Fineract configuration before you continue.
Configure tellers and cashier assignments
Create the tellers in the agreed offices, link each cashier to a teller and set the currency and opening configuration your branches use. Your Fineract administrator makes the changes in a non-production tenant, and the operations lead checks each record against the approved office map. The output is a configuration export or a documented record of every teller and cashier assignment, with a second person's sign-off that the records match the design.
Test allocation and settlement with sample branch days
Run scripted branch days in a test environment, covering cash allocation to a cashier, customer transactions, cash returned by the cashier and settlement at close. Testers include at least one case of a shortage, an overage and a reversal, since these are where configurations usually fail. The output is a test script log showing expected and actual balances for every case, with each failure recorded and retested. Use this step to confirm your own scenarios rather than assuming the platform handles them.
Reconcile test results to the ledger
Take the cash balances and journal entries from each test branch day and reconcile them to the general ledger mapping from the design step. Your finance team confirms that every movement lands in the expected account, that totals per office tie out and that every difference has a recorded explanation. The output is a reconciliation workbook with zero unexplained differences, signed by the finance owner. If a difference remains, return to the mapping or configuration step rather than adjusting the ledger by hand.
Train branch staff on the approved process
Train each teller, cashier and approver on the roles, the daily steps, the settlement routine and the exception procedure, using the scripted scenarios from testing. Branch managers confirm that each person has the permissions their role needs and no others. The output is a training record listing who completed which module, plus a short, approved procedure that staff can follow at the counter.
Run a parallel close before go-live
Operate the new teller process alongside your existing cash handling for a period agreed in advance, then compare the Fineract cash balances and ledger postings with the legacy records for each branch. Finance and operations review every variance until the parallel results agree or each remaining difference has an approved explanation. The output is a parallel close report with the sign-off that allows cutover, along with a rollback plan if a branch cannot reconcile at go-live.
Loading opening cash balances and staff data into Fineract
Before any teller session opens, the office hierarchy, staff records, opening cash positions and the cut-off date must all exist and agree with each other. Offices form the tree that tellers, cashiers and vaults hang from, so a branch created late or under the wrong parent office will misroute cash activity later. Staff records must be in place for every person who will be assigned as a cashier, and each cashier or vault needs a documented opening balance by currency. Decide the cut-off date and time first, because every opening figure is only meaningful as at that moment. Confirm in your own environment, against the Fineract version you are deploying, which teller, cashier and staff fields the import templates and APIs accept, and whether opening cash positions can be loaded through them at all or must be entered through the application after go-live.
The opening cash balances must be agreed with the general ledger as at the cut-off. Before loading anything, have finance produce the physical count per vault and cashier, the value of cash in transit to and from branches, and the matching ledger balances for the cash accounts you have mapped. Any difference between the count and the legacy ledger should be explained and cleared before the first Fineract session, not absorbed into a suspense entry. Ask your implementation partner or the vendor to show how the cut-off balances will be posted in Fineract's accounting, and which journal entries, if any, the migration creates. Do not assume that loading a balance into a cashier record also updates the general ledger.
Finally, check the migration tooling against what the import mechanism actually supports for these records. Review the official Apache Fineract platform documentation for the import and API options in your release, and test each load in a non-production tenant first. Record which steps are scripted, which are manual, and who signs off each count. Plan a reconciliation run after the load that compares Fineract cashier balances, vault balances and ledger cash accounts to the signed count sheets, and hold go-live until the three agree.
What drives teller implementation effort and cost
This table lists the factors that change how much design, build, testing and parallel running a Fineract teller and cashier rollout needs. Read each row as a lever: the middle column shows how the driver raises or lowers effort, and the right column shows how to keep it manageable. The main takeaway is that branch count and cash-difference rules usually matter more than the software setup itself.
| Driver | Effect on effort and cost | How to keep it manageable |
|---|---|---|
| Number of branches | Each branch adds office setup, teller and cashier mapping, and branch-specific testing and training | Pilot one or two branches, then roll out with a repeatable office setup checklist |
| Tellers and cashiers per day | Higher daily volume raises the number of cash movements to reconcile and the load on end-of-day checks | Confirm peak volumes with branch managers and size teller counts from real transaction history |
| Currency count | Each additional currency adds exchange handling, separate cash balances and separate ledger mappings | Limit cash handling to currencies the branches truly need and configure the rest later |
| Depth of ledger mapping | Mapping cash, vault and difference accounts to the chart of accounts drives most accounting design work | Agree the chart of accounts and cash account structure with finance before configuration starts |
| Custom front-end work | Fineract is headless, so any teller screen beyond the Mifos web application or your own front end is extra build and support | Use existing front ends where possible and scope custom screens separately in writing |
| Approval rules for cash differences | Thresholds, approver roles and escalation paths add configuration, testing and operational procedure | Write the difference policy first, then test each approval path with sample shortfalls and overages |
| Integration with core teller or vault systems | Links to existing cash management or vault tools need interface design, reconciliation logic and failure handling | Confirm which system owns each cash balance before building any data exchange |
| Parallel running | Running old and new cash processes side by side extends testing, reconciliation and staff training | Set clear exit criteria for parallel running and time-box it in the project plan |
How teller data connects to the rest of the platform
How do teller cash movements reach the general ledger in Fineract?
Teller and cashier transactions flow into Fineract's accounting layer, so cash movements should appear as journal entries once the accounting configuration maps them to ledger accounts. The mapping decides which GL account each cash movement debits or credits, so confirm the exact behavior for your version and accounting mode before go-live. Test one cash allocation, one settlement and one variance from start to finish, then compare the resulting journal entries with the branch count sheet. Decide early where Fineract's ledger ends and your ERP begins, and document that boundary. Keep the account mapping under change control, because a later change to a cash account can misstate historical branch balances.
Which client transaction records does teller activity create?
Teller activity sits alongside client transaction records, so a cash receipt for a loan repayment or a savings deposit should be traceable to the client, the account and the teller who took the cash. Confirm which teller, cashier and batch reference fields your version stores on each transaction and whether they can be searched through the API. Agree on a naming convention for teller and cashier codes before data entry starts, because these codes will appear in audit trails, reconciliations and support tickets. Test a reversal and a correction to confirm that the original record remains visible and that the audit trail shows who made each change.
Can teller staff sign in to Fineract through our identity provider?
Fineract's README shows OAuth2 and HTTP basic authentication, so teller users can be authenticated through an OAuth2 integration. Confirm how identity provider groups or claims map to Fineract users, roles and permissions in your version, since teller access depends on which branch and cashier role each person holds. Plan how cashier assignments are created, changed and removed when staff move or leave, and who approves those changes. Before any real deployment, replace the default development login of mifos and its password, and make sure the service account used by integrations has its own scoped credentials.
Should we use the Mifos web app or build a custom branch application?
Fineract is headless and does not provide its own user interface, so teller screens come from a front end you select or build. The README points to the Mifos X web application as the front end in its Kubernetes example. Confirm whether the teller workflows your branches need, such as cash allocation, settlement and count sheets, are covered in the version you plan to run. A custom branch application gives you control over the cash count screens, offline behavior and approvals, but it also means you own the design, the testing and the upgrade path for those screens. Compare both options against a written list of teller tasks before choosing.
Does Fineract publish teller events to ActiveMQ or Kafka by default?
No. Fineract can publish external business events, such as ClientCreated, to ActiveMQ, other JMS brokers or Apache Kafka, but this is disabled by default according to the README. Enable it deliberately, and only after deciding which teller events downstream systems need, such as cash receipts, allocations or settlements. Confirm the event names and payloads your version emits before writing consumers. Event publishing adds a dependency: consumers must handle retries, duplicates and ordering, and the broker needs its own monitoring, access control and retention settings. Treat each enabled event as a data flow that needs an owner, a schema and a test.
How should teller workloads be placed across Fineract instances?
Fineract's documentation describes read, write and batch instance types set by environment variables, and recommends one write instance, one batch instance and multiple read instances on database read replicas for high load. Teller postings are write operations, so they belong on the write instance, while reporting and reconciliation queries can move to read instances. Liquibase database migrations run only on write instances, which makes them a planning item for any upgrade. The Close of Business batch job can run for several hours on large deployments, so schedule teller settlement, cash counts and batch windows so they do not collide. Confirm the exact configuration keys in the platform documentation.
How do we build teller reports and daily cash reconciliations?
Build daily cash reconciliations from the teller, transaction and journal data, and confirm which report endpoints and report options your Fineract version supports before designing the report set. Reports that read client and cash data must be secured, and the 1.15.0 SQL injection fixes are a reason to confirm you are on a version that includes them. Define the reconciliation rules in writing: which totals must match the cash count, which variances need manager approval, and how each variance is cleared. Test the reports against a known set of teller transactions so that finance and branch staff can agree on the expected results before go-live.
Can our own team connect teller data without an implementation partner?
Your team can do this if it has Fineract, PostgreSQL, identity and integration skills, and the time to test the accounting and cash workflows end to end. The work divides into ledger mapping, identity, the front end, event publishing, reporting and operations. Fineract's README warns that a production deployment can be complex, costly and time-consuming, and that the project does not provide a comprehensive production deployment guide, so budget for that effort explicitly. DeployOpen plans, builds and documents these integrations inside your infrastructure under a written, fixed scope with deliverables and timelines agreed before work starts, and offers ongoing support as a retainer.
How DeployOpen scopes and delivers teller and cashier work
DeployOpen scopes teller and cashier work as a fixed engagement with a written statement of which branches, roles, cash locations and general ledger accounts are in scope. Before any configuration starts, we walk through each branch's real cash day with your operations team: who opens a teller, how cash moves from vault to cashier and back, how shortages and overages are handled, and which journal entries the business expects at settlement. Those answers become the acceptance criteria. The written scope also states what is excluded, such as custom reports, cash-in-transit integrations or changes to the chart of accounts, so that a quote can be compared line by line against your own team's effort.
Delivery covers configuring tellers, cashier assignments and cash allocation and settlement in the environment you run, then testing those settings against branch scenarios written with your staff. Typical scenarios include a full cashier handover at shift change, a settlement with a shortage, an allocation reversed on the same day and a teller closed with an unsettled balance. Each test run is recorded with expected and actual results, the posted journal entries and a reconciliation of cash movements against the general ledger, so your auditors and finance team can see the evidence rather than a summary. Your own staff should confirm the exact behaviour of each permission and reversal in your Fineract version before the test plan is signed off.
At handover, DeployOpen provides a runbook for branch supervisors and finance, role-based training materials and a short reconciliation procedure for daily and month-end checks. DeployOpen prepares these controls, configuration records and evidence, but it does not issue audit reports, attestations or certifications; independent auditors and certification bodies do that work. Ongoing support, such as changes to cashier roles, new branches or reviews after platform upgrades, is available as a retainer agreed separately from the fixed-scope delivery, so the cost of that support is quoted on its own terms.
