Apache Fineract collection sheets

Collection sheets in Apache Fineract for meeting-day collections

A field lending organization that collects loan repayments and savings deposits at center meetings needs its back office to match every shilling or dollar collected in the field to the postings in the ledger. In Apache Fineract, the mechanism for this is the collection sheet: a per-meeting list of what each client or group owes and what each account can take, which the field officer completes and then submits as bulk repayments and deposits. A collection sheet is not a built-in screen. Fineract is headless and exposes REST APIs without a user interface, so the sheet is generated and saved through an API call from a front end. The Mifos X web application, which the Fineract README references in its Kubernetes example, is one such front end. A custom mobile or web client is the other common route. Confirm which front end your organization will use, and check its collection sheet support against the Fineract release in use, before the field process is designed.

Plan collection sheets before go-live, not after the first meeting cycle. The decisions that are hard to change later include how centers and groups map to meeting calendars, which products and savings accounts appear on the sheet, how partial payments and unpaid amounts are handled, and whether the field officer works offline and syncs later. Each of these affects the API calls the front end makes and the accounting entries that follow. Before committing, confirm with the vendor or in a test environment the exact collection sheet endpoints, request fields and options in your release, since these details are not set out at this level in the platform documentation. Then run a reconciliation test: a known set of repayments and deposits saved from a sheet should produce the same cash, loan and savings balances, and the same journal entries, that your finance team expects. Treat that test as a go-live gate.

Center sheets, individual sheets and bulk saves: which fits which meeting

This table compares center-level sheets, individual sheets and bulk repayment and savings saves for field collections in Fineract. Read each row against your meeting pattern, then use the final column to confirm how the chosen Fineract release handles that step before you commit to a workflow.

Option	What it suits	What the officer must check	What to confirm in the chosen Fineract release
Center sheet for group meetings	Centers where clients meet together and pay at one sitting	Every group member is on the sheet, attendance and amounts match the meeting roll, and no client is missed or duplicated	Which center and meeting dates the sheet can be generated for, and how the sheet is printed or exported
Individual sheet for one-by-one collection	Officers who visit clients separately or collect from individual borrowers and savers	Each client's due amounts, arrears and any early or partial payments are correct before saving	Whether individual lines can be generated and filtered by officer, and how due amounts are shown
Bulk repayment save	Large meetings where many loan repayments are entered in one batch	Each line maps to the correct loan and amount, and rejected lines are reviewed before the batch is closed	How batch repayments are submitted, whether partial failures are reported per line, and the batch request format
Bulk savings deposit save	Meetings where members deposit into savings accounts alongside loan repayments	Deposit amounts, account numbers and transaction dates are correct and match the cash counted	Whether savings deposits can be included in the same batch as loan repayments, or need a separate step
Mixed repayment and deposit in one meeting	Centers where loan repayments and savings deposits are collected at the same sitting	Totals by product line are checked against the cash box before the meeting is closed	Whether one sheet can carry both product types, and how each transaction is recorded in the ledger
Offline entry then later save	Field areas with weak connectivity where entries are captured first and saved later	Entries are not lost or saved twice, and the officer knows which meeting each entry belongs to	Whether the chosen client application supports offline capture, and how it handles duplicate submissions

Setting up collection sheets in Apache Fineract step by step

This sequence takes a field lending team from an unconfigured Fineract tenant to a tested meeting-day workflow, where collection sheet totals match the transactions posted and the cash counted in the field.

Confirm the release and PostgreSQL target
The implementation lead records which Fineract release and which PostgreSQL version the tenant will run, and checks both against the project's current stable release and its release policy. The Fineract website lists 1.15.0 as the current stable release, and the README recommends PostgreSQL, so confirm the target before any configuration work begins. Confirm the Docker image tag and the database driver with the release notes. The step is done when the target is written into the environment record and the team can state which release their sheet behavior was tested against.
Define the office, centers and groups
The field operations lead and the implementation consultant create the office in Fineract, then the centers and groups that hold the clients who meet on the same day. Each center carries its meeting calendar, and each group is linked to its center and its assigned loan officer. Verify the structure by pulling the center list and checking that every client in the pilot population appears under exactly one group and one center. A mismatch here will produce sheets that omit clients or double-count them, so resolve every orphan record before moving on.
Assign meeting calendars and officer access
Set the recurring meeting dates for each center so that Fineract can generate sheets for the correct day. Then assign each field officer to the centers they serve and create their user roles with only the permissions needed to view and post collections for those centers. Ask the security owner to review the role definitions, since the README warns that default credentials must be changed before any real use. The step closes when a test officer account can open the sheet for its own center and cannot open a sheet for a center it does not serve.
Configure products and receiving savings accounts
Configure the loan products and savings products whose repayments and deposits will appear on the sheet, including the currency, repayment schedule and any mandatory savings linkage that the field model requires. Confirm with the lending team which charges and due-date rules apply, because these drive the amounts shown on each line. Create a test client and loan in the non-production tenant to confirm that the sheet reads the product correctly. The step is complete when a sample schedule matches the expected installment on the product specification signed off by the business.
Test sheet generation on a non-production tenant
Load a representative set of clients, loans and savings accounts into a non-production tenant, then generate the center and individual collection sheets for a scheduled meeting date. Compare the sheet totals for principal, interest, fees and savings against the expected figures computed independently from the test schedule. Repeat the run with at least one edge case, such as a client with a partial payment or a closed account, and record each difference. Do not proceed until every difference has a documented cause and a fix or an accepted business rule.
Save bulk repayments and deposits in test
Enter the collected amounts for the test meeting through the bulk repayment and savings deposit flow, using the same sequence the field team will follow on the day. Check that each saved line creates the expected transaction against the right loan or savings account, and that no line is posted twice when the batch is retried. Export the resulting transactions and compare their total against the sheet total and the cash counted in the test envelope. The step is done when the three figures agree and the team has written down the retry behavior it observed.
Run a pilot meeting with reconciliation
Run one live meeting at a single center with a small group of clients, using the production configuration and the approved cash-handling procedure. At the end of the meeting, reconcile the cash physically counted by the officer, the collection sheet total, and the transactions posted in Fineract, and record any variance with its cause. Ask the finance team to confirm that the posted transactions flow to the accounting ledger as designed. The pilot is complete when the reconciliation closes with no unexplained difference, and the team agrees the rollout to other centers.

Reconciling cash collected in the field after each meeting

The gap between cash handed over and transactions posted is the main reconciliation risk. A field officer collects cash, the back office saves repayments and deposits in Fineract, and until both sides match, the cash log and the loan and savings ledgers disagree. Close each meeting in a fixed order: the officer counts cash and cheques against the collection sheet, records any unpaid or partial lines, and signs the sheet. The back office then saves the bulk repayments and deposits, compares the Fineract totals for that center and date with the signed cash total, and clears every difference before the next meeting. Confirm with your implementation team which Fineract screens and reports show per-officer and per-center totals for a given date, since the exact views depend on the deployed version and front end.

Partial payments, reversals and shortfalls each need a written rule before go-live. A partial repayment should be entered as what was actually received, with the unpaid balance left in the schedule so it shows as arrears, not written off by the officer. A reversal, such as a cash payment rejected later or a keying error, should go through the reversal or undo path your team has tested, with a reason code and the approver recorded, rather than an overwrite. A shortfall between cash and posted amounts is held as an open item under a named owner until it is explained, and it is never netted against another client's payment. Decide who can approve each action and how long an item may stay open, and test these paths in a non-production tenant first.

Keep the transactional evidence in Fineract and the cash custody evidence in the organization's cash log. Fineract holds the loan and savings transactions, their dates, the officer and the office, which is what auditors and funders will trace. The cash log should hold the signed sheets, the counted totals, the bank or safe deposit references and the sign-off on each shortfall, linked to the Fineract batch or transaction identifiers. Before the first live day, agree the controls in writing: a daily total check per officer, a second person to review every reversal, a rule that no sheet is closed with an unexplained difference, and a retention period for the paper sheets. Ask your team to show how a single meeting can be traced from the cash log to the posted transactions and back.

How connectivity and the officer device change the design

When the officer's device stays online through the meeting, the simplest design saves each collection sheet directly to Fineract as the officer works through it. Each repayment and savings deposit posts when entered, so the branch sees balances move almost immediately and cash counted at the end of the meeting can be checked against the system straight away. The trade-off is that every slow or failed request is visible during the meeting, so the front end must handle retries and duplicates cleanly.

Duplicate submissions: A tapped button or repeated request on a weak signal can post the same repayment twice. Test whether the front end disables submit while a request is pending and how the API responds to a repeated request.
Partial saves: A sheet with many rows may save some lines and fail on others. Confirm how errors are returned per line and whether the officer can see which rows did not post.
Session expiry: A long meeting can outlast a login session. Confirm the token lifetime and the behavior when it expires halfway through a sheet.
Peak load at meeting times: Many officers may submit in the same hour. Ask the platform team how the write instance handles bursts and whether balance reads run on separate read instances.

Before committing, confirm with the front end owner which errors are retried automatically, and check the Fineract platform documentation for the instance types and API behavior your version supports.

Securing field officer access and cash data in collection sheets

Collection sheets put write access to repayments and savings into the hands of many field officers, often on shared or personal devices. The six controls below decide who can post cash, from where, over which connection, and how each posting can be traced afterwards.

Replace the default development login

Fineract's README ships a default development login (username mifos, with a known default password) that must be changed before any real deployment. Confirm that the default account is disabled or renamed in every tenant, not only the first one, and that no field officer shares a generic account. Check the change in each environment, including staging copies that hold live client data.

Choose OAuth2 or basic authentication

The README documents both OAuth2 and HTTP basic authentication. Basic authentication sends credentials with every request, so it only makes sense behind TLS and for a small set of trusted service callers. Decide which path the chosen front end uses for officers, and confirm with the Mifos web application or your own client how tokens expire and how a lost handset is revoked.

Enforce HTTPS only

The Fineract documentation strongly encourages HTTPS only and configures TLS through environment variables such as FINERACT_SERVER_SSL_ENABLED. Confirm that plain HTTP is closed at the load balancer or gateway, that certificates are issued and renewed for every host the handsets use, and that the mobile client rejects untrusted certificates. Cash posting traffic should never fall back to an unencrypted path.

Limit each officer to their offices

Fineract scopes what users see through the office hierarchy, so a field officer's role should allow repayment and savings posting only for the centers and groups in their own branch. Test this with a user from one branch against a client in another, and confirm that the collection sheet report cannot be generated for an office outside the user's scope. Review role assignments whenever staff move or leave.

Manage field handsets as devices

Officers collecting cash often use company or personal phones and tablets with offline sheets. Decide whether devices are enrolled in mobile device management, whether local storage of collection sheets is encrypted, and how a stolen device is wiped and its tokens revoked. Confirm that the front end does not cache credentials or unsynced repayments in a form that survives logout.

Audit every saved repayment

Each bulk repayment or savings deposit saved from a collection sheet should leave a record that identifies the officer, the meeting, the amounts and the time. Confirm that audit entries cannot be edited by the officers who created them, that they are retained for your policy period, and that they reconcile to the cash counted at close of the meeting. Test by reversing a posting and checking that the trail shows both entries.

What usually goes wrong with collection sheets in live meetings

The most common failure is a collection sheet generated before the meeting calendar and client assignments are final. A sheet is a snapshot of who is expected to pay, how much, and against which center. If a center's meeting date moves, a client joins or leaves a group, or a loan officer is reassigned after the sheet was printed or exported, the officer collects against a list that no longer matches the books. The check is to make sheet generation a step in the meeting-day runbook, not a weekly task. Before each meeting, regenerate the sheet for the center, compare its client list with the current group membership, and confirm the calendar entry for that date. Test this in a staging copy with at least one group moved and one meeting rescheduled, and confirm how your Fineract version treats sheets generated before those changes.

The second pattern is saving against the wrong center after a transfer. When a client moves between groups or centers, or between offices, the repayment can be posted to the loan in the new structure while the officer's paper sheet still lists the old one, or the reverse. This is most likely in the first meeting after a reorganization. Treat transfers as a freeze point: agree a cut-off after which sheets are rebuilt, and have the officer confirm each line against the client's current group before saving. A test case should replay a bulk repayment for a client who was transferred the previous day and confirm that the posting, the officer and the group in the output all match the intended destination. Confirm the exact transfer behavior for your release with the project documentation and your own configuration before go-live.

The third and fourth patterns are technical. A dropped mobile or tablet connection often leaves the officer unsure whether a bulk save succeeded, so the same batch gets submitted twice. Fineract does not make that safe by default, so the design should put a unique reference on each collection submission, make the field app check for an existing result before retrying, and reconcile totals at the end of the day. Finally, the end-of-day Close of Business Day job competes with officer activity when both run on a shared write instance. The Fineract README notes that this job can run for several hours on large deployments and can be partitioned across workers, so its duration on your deployment must be measured rather than assumed. Schedule a load test that runs the job while simulated officers save collections, record job duration and save latency, and set the meeting-day cut-off from those results.

Limits to confirm before designing collection sheets in Fineract

Collection sheets depend on endpoints, front-end features and database behavior that differ between releases and deployments. The six items below are the points to confirm with the vendor, the release notes or your own tests before the workflow is designed, because each one changes what officers can do on meeting day.

Sheet and bulk endpoints in the target release

Confirm which collection sheet, bulk repayment and bulk savings endpoints exist in the exact Fineract release you plan to run, and what request and response shape each one uses. Fineract ships quarterly releases, so an endpoint in the documentation for one version may not be present in the version you deploy. Check the request payload for each transaction type and whether partial failures are reported per row. Record the answers against the release number you pin.

Offline entry in the chosen front end

Fineract is headless and provides no user interface of its own, so offline collection depends entirely on the front end you select. Confirm whether the front end can cache a sheet on a device without connectivity, queue repayments and savings deposits locally, and sync them later without duplicating transactions. Ask how conflicts are resolved if a client's loan changes while the device is offline. Do not assume offline support because the Mifos X web application is the reference front end in the project's Kubernetes example.

Maximum practical sheet size on the target database

Measure how long a sheet takes to load and how long a bulk save takes for a center of realistic size on the PostgreSQL version and hardware you will run. The project recommends PostgreSQL as the database and deprecates MariaDB and MySQL, so test on that platform. Record the largest sheet your team can load and save within the officer's tolerance, and the point at which the API or database starts to time out. Set the limit from the test result, not from a general expectation.

Effect of the write, batch and read split

Confirm how your instance layout affects officers. Writes, including bulk saves, go to the write instance, while the batch instance runs the close of business job and read instances serve queries from replicas. Check whether a sheet generated from a read instance can be stale when a repayment was just saved, and how long replica lag is in your environment. Also confirm whether heavy close of business processing on the batch instance can slow saves during collection hours, and schedule the job around field activity.

Reversal behavior in bulk saves

Confirm how a reversed or undone transaction behaves when it was saved as part of a bulk request. Determine whether each row is reversed individually, whether the reversal is recorded with the original officer and time, and whether it affects the cash position reported for that day. Check whether reversals posted after the meeting day are allowed under your accounting period and closure settings. Write down the procedure for correcting a wrong amount before the officer leaves the center.

Officer workflow coverage in the front end

Map every step an officer takes on meeting day, from opening the center and marking attendance to recording a cash handover at the end, and check each step against the chosen front end. Some steps may need the API directly, a custom screen or a separate reconciliation report. Identify which steps need a supervisor approval and whether the front end supports it. Document the gaps and the work needed to close them before you commit to a design.

Questions buyers ask about Apache Fineract collection sheets

What drives the cost of building collection sheets in Apache Fineract?

The main cost driver is how many meeting-day patterns your field model contains, not the sheet screen itself. Cost rises with the number of product types collected at a meeting, the number of centers and meeting calendars, the rules for partial payments and arrears, the cash reconciliation steps, and the reports your finance team expects at the end of each day. Costs fall when product rules are settled before build and when officers and centers are already clean in the system. In a quote, ask for the work split between configuration, any custom development around the sheet, testing with real meeting-day scenarios, and training. Ask whether any part is recurring, such as support or upgrades, and which parts are one-time.

How long does a collection sheet pilot usually take?

Pilot length depends mainly on how much of the field process is already decided. The sheet itself can be configured quickly, but timing is set by the decisions around it: confirming which products are collected at a meeting, how repayments are split across loans and savings, how cash is counted and banked, and who signs off a reconciliation. Data quality matters too, because officers, meeting calendars and group membership must be correct before a sheet can be trusted. A pilot should run through several real meeting days across more than one center. Ask any partner to state the pilot timeline in the written scope, with the decisions you must make and the dates on which you must make them.

What must our team provide before a collection sheet build starts?

Your team needs to provide four groups of input. First, officer lists with their offices, the centers and groups each officer covers, and the staff records linked to user accounts. Second, meeting calendars for each center, including holidays and any dates that move. Third, product rules for every loan and savings product collected in the field, covering repayment order, penalty handling and any overpayment policy. Fourth, cash procedures: how officers hand over collections, what counts as a shortfall, who approves variances and where the daily cash figure is recorded. Missing any of these usually leads to rework during testing, so ask the partner to confirm the list in writing before the build begins.

Can an internal team build collection sheets for Fineract without a partner?

Yes, an internal team can build collection sheets if it has the skills and time to do so. Fineract is headless and exposes REST APIs, so the sheet logic, the front end used by officers and the reconciliation process must all be designed by you. The skills needed include Fineract configuration, API integration, database and environment operations, testing against meeting-day scenarios and close-of-business awareness. The Fineract documentation and source code are the primary references for this work. The project's own README warns that a production deployment can be complex, costly and time-consuming, so assess your team's capacity honestly before deciding. Many organizations choose a hybrid model in which a partner builds the first version and the internal team takes over operations.

What does a fixed-scope DeployOpen engagement cover for collection sheets?

A DeployOpen fixed-scope engagement covers the work agreed in writing before it starts. For collection sheets, the scope normally states which centers and products are in the first release, the sheet and reconciliation outputs, the integration points with your environment, the test plan and the handover material. DeployOpen plans, implements, customizes, integrates, documents and supports self-hosted open-source platforms inside your own infrastructure, so the deployment stays in your cloud accounts, data centers or air-gapped network. Ask for the deliverables list, the acceptance criteria for a pilot meeting day and the assumptions about your inputs. Anything not in the written scope, such as additional products or reporting, should be quoted as a change.

How do Fineract upgrades affect collection sheets?

Upgrades can change the behavior that collection sheets depend on, so they should be planned as part of the sheet, not as a separate task. Fineract publishes quarterly releases and archives end-of-life releases, so your version will move over time. Before each upgrade, regression test the sheet calculations, repayment allocation, savings deposits, batch jobs and reconciliation reports against a copy of production data. The project's release policy and documentation should be read for each target version. Ask any partner how upgrade testing is scoped, whether it is included in fixed-scope work or sold as a separate service, and who owns the decision to move a version.

What does recurring support look like after go-live?

Recurring support covers the work that continues after the first meeting days run correctly. Typical items include monitoring the batch and reconciliation jobs, fixing defects found in the field, updating meeting calendars and staff assignments, reviewing sheet output after product changes, applying security patches and handling upgrades. Support can be bought as a retainer or handled internally, and the choice depends on how often your product rules change and how many officers depend on the sheets. DeployOpen offers ongoing support and upgrades as retainers. Ask for the response expectations, the escalation path, the change process for product rules and what is excluded from the retainer before you sign.

How DeployOpen works on this

DeployOpen plans, implements, customizes, documents and supports self-hosted open-source platforms inside your own infrastructure. For collection sheets in Apache Fineract, we start from your meeting calendar, repayment rules and cash handling practice, then agree the work in writing before any configuration begins.

How we scope

We map your meeting-day process, from sheet printing to cash handover, against the Fineract features in your chosen release.
The written scope lists which sheet types, bulk repayment paths and reconciliation reports are included and which are excluded.
Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts. Ongoing support is available as a retainer.

How we build

We configure centers, meeting calendars and office scope in a non-production tenant, then test sheet generation against sample client lists.
We test bulk repayment and savings deposit posting for partial payments, overpayments and clients absent from a meeting.
We check that cash totals on each sheet reconcile to ledger postings before any field officer uses the process in production.

How we hand over

You receive configuration records, test scripts with results, and a runbook for field officers, branch staff and supervisors.
The handover covers the reconciliation procedure, exception handling for failed postings and the sign-off steps for end-of-day cash.
We walk your operations and support staff through the process and record open questions for your own team to confirm.

How we support

Support can be taken as a retainer covering fixes, reviews of configuration changes and updates when your Fineract release changes.
Changes to meeting calendars, products or reconciliation reports go through the same test and documentation steps as the original build.
Ask any provider for written confirmation of response scope, upgrade responsibilities and what happens to configuration on each platform release.

Collection sheets for field officers in Apache Fineract