How reconciliation proves a Fineract migration is right
Reconciliation proves a Fineract migration is right by comparing what the legacy system says with what Fineract says, measure by measure, before anyone switches off the old platform. A team moving a live loan and savings book needs that evidence, not assumptions. The checks cover client and account counts, outstanding principal and accrued interest per loan, savings balances per account, and a general ledger trial balance that matches at the level the finance team closes on. Planning this work usually takes as much effort as the data load itself. The duration depends on portfolio size, the number of products, and how many systems feed the ledger, so ask for the reconciliation scope in writing before estimating it.
Fineract is headless. It ships REST APIs and no user interface of its own, so every reconciliation figure has to come from API reads or from database and report exports that your team controls. Decide early which source of truth each figure comes from, and whether the comparison runs against the Fineract API, a read replica of its PostgreSQL database, or a scheduled report. Confirm the read paths with your own environment and with the Fineract documentation at Apache Fineract platform documentation before you write comparison scripts, because a figure read from the wrong place can match while the books still disagree.
Treat the reconciliation pack as a deliverable with an owner, a tolerance and a sign-off for each measure. A count mismatch, a principal difference or a ledger variance should either be explained to the cent and traced to a documented cause, or it blocks cutover. The same comparison then repeats during the parallel run, where both systems process live transactions for a defined period and the outputs are compared daily. Agree the exit criteria for that period with finance, operations and risk before the run starts, so the decision to cut over rests on recorded evidence.
Which source reconciliation checks map cleanly to Fineract
This table pairs each source-system reconciliation check with its nearest Fineract equivalent, whether that is an API resource, a report, an accounting entry or the business date. Rows marked as likely variance sources need an explained difference, not a forced match, so treat the right-hand column as the starting point for investigation rather than a guarantee of equal totals.
| Check | Fineract equivalent | Mapping quality |
|---|---|---|
| Client and account counts by office | Client and loan or savings account list endpoints, filtered by office and status, compared with the source extract taken on the same business date | Maps cleanly if both extracts use the same status definitions, such as active, closed and pending approval |
| Outstanding principal per loan | Loan retrieval with repayment schedule and outstanding balances, compared with the source principal balance on the cutover date | Maps cleanly for loans loaded as balances; differs for loans replayed from history if schedules were regenerated |
| Outstanding interest per loan | Loan schedule and summary fields for accrued and unpaid interest, read against the business date used for the source extract | Variance source: interest recalculation, day-count basis and accrual timing can shift totals; document each difference |
| Savings account balances | Savings account retrieval for running balance, compared with source ledger balances at the same cutover timestamp | Maps cleanly for balances, but holds, overdraft settings and posting timing need confirmation in the source data |
| General ledger trial balance | Accounting reports and journal entry listings for the cutover date, compared with the source trial balance by mapped GL account | Maps only after the chart of accounts mapping is signed off; account-level totals should be checked before the overall total |
| Open items and suspense balances | No single equivalent; confirm which Fineract journal entries, pending transactions or manual entries represent each source open item | Usually fails here: open items often have no direct Fineract field and need a documented treatment |
| Accrual timing at cutover | Business date and close of business run status, compared with the date the source system accrued interest and fees | Variance source: if the Fineract business date and the source accrual date differ, totals will not match without an explained adjustment |
| Product rule effects | Product configuration as applied to each loan or account, compared with source terms such as rate, fee and grace period | Variance source: where a product rule in Fineract calculates differently from the source, the difference must be explained rather than adjusted away |
Fineract APIs and reports used to pull reconciliation data
Reconciliation depends on extracting the same facts from both the legacy system and Fineract in a repeatable way. The cards below cover the documented read paths, how tenant scoping and read instances affect extracts, and how to confirm report support before you commit to a method.
REST API reads for core entities
Clients, loans, savings accounts and journal entries can be read through Fineract's REST API, which gives you a programmatic way to pull counts, identifiers, statuses and balances. Build each extract against a fixed list of fields and record the exact endpoint and parameters used, so the same query can be rerun after every load. Check in the Fineract documentation for your release which fields each read returns, especially for loan repayment schedules and account balances. Pay attention to pagination and filtering, since an extract that silently truncates results will look like a reconciliation break.
Tenant scoping with the platform header
Fineract is multi-tenant, and API requests carry a Fineract-Platform-TenantId header that selects the tenant whose data is returned. A reconciliation extract sent without the correct header can read the wrong tenant or fail in a way that is easy to misread. Record the tenant identifier as part of every extract's metadata, and run a check that the counts returned for a known test tenant match expectations before comparing production data. Confirm how your environment maps tenants to databases before you rely on any single extract.
Read instances for extract workloads
The Fineract documentation describes read, write and batch instance types set by environment variables, and recommends multiple read instances on database read replicas for high load. Running large extracts against a read instance keeps reporting queries away from the write instance that handles live transactions and the parallel run. Ask your platform team whether a read replica is provisioned, how far it lags behind the primary, and whether lag is measured before each extract. A cut taken during replica lag can produce a false difference, so record the timestamp of the last replicated write.
Reconciling tool-based loads with the same extracts
Loads performed with Excel bulk import or scripted API calls should be checked with the same extracts used for the comparison, not with the import tool's own success messages. Run the identical extract before and after each load batch and compare counts and balances against the source file or script output. An illustrative example: if an import reports 500 clients created but the client extract returns 497, the gap must be explained before any further load. Keep the extract definitions under version control so every migration method is measured against one standard.
Confirming report availability and formats
Fineract exposes reporting features through its API and documentation, but the available reports, their parameters and export formats can vary by release. Before you design the reconciliation pack, confirm in the documentation for the release you deploy which reports exist, which can be run by a service account, and whether output is available in a machine-readable format. Test each report against a non-production copy of your data. Where a needed report is missing or awkward to export, plan an API-based extract instead and document the choice.
Sequence from reconciliation design to cutover and decommission
This sequence turns reconciliation from a one-time check into a controlled path: agreed rules first, then repeated trial loads, a timed parallel run and explicit cutover criteria. It ends with the source system retired only after a defined hold period, so each step produces evidence the business and auditors can rely on.
Define reconciliation rules and tolerances with finance
Finance, operations and the migration lead agree in writing which figures must match, at what grain and within what tolerance. Cover client and account counts by status and office, outstanding principal and interest per loan, savings balances, and general ledger trial balance totals by account and currency. Record who signs each rule and how exceptions are classified. This step is done when the reconciliation specification is approved and every rule names its source report in the old system and its equivalent in Fineract.
Map source and target reports before any load
Identify the report or query that produces each reconciled figure in the legacy system, then the matching Fineract report, API response or database view. Confirm the cut points differ: legacy systems often close at a different time than Fineract's close of business batch. Document the definition of each balance, such as whether accrued interest is included, so both sides are compared on the same basis. Done when every rule has a paired source and target calculation and the differences in definition are written down.
Run count and balance checks on test loads
Load the migration files into a non-production Fineract tenant and run the reconciliation rules against the legacy extract taken at the same cut point. Start with counts of offices, staff, clients, groups, accounts and journal entries, then compare balances loan by loan and account by account. Investigate each mismatch to its cause, whether mapping, rounding, currency, interest recalculation or load order. Done when the test load produces a difference log in which every item is explained or assigned to a fix.
Repeat the reconciliation after each trial migration
Each full trial migration starts from a fresh environment and a fresh extract, so earlier results cannot be reused. Rerun the complete rule set after every change to mappings, scripts or templates, and record the results against the version of the load files used. Track whether the number of unexplained differences falls with each trial. Done when two consecutive trials on the same extract produce identical reconciliation results, which shows the load is repeatable.
Confirm close of business timing before comparing balances
Fineract applies daily interest, accruals and status changes through the Close of Business Day batch job, and the README notes this can run for several hours on deployments with millions of accounts. Balances taken before that job completes for a business date will differ from balances taken after it. Agree a daily comparison point that falls after COB has finished in both systems, and confirm with the operations team how long COB takes on production-sized data. Done when the comparison time is fixed and a COB completion check is part of the daily run.
Run a timed parallel period with daily comparison
For a defined period, both systems process real transactions. Operations records each transaction in the legacy system and in Fineract, and the reconciliation rules run every business day at the agreed comparison point. Differences are logged with an owner and a clearing deadline. Because Fineract's external events are disabled by default, confirm whether downstream systems need them during this period. Done when the parallel period has run the agreed length with daily reports signed off and every open difference either cleared or accepted by finance in writing.
Agree cutover criteria and the business date
Before cutover, the steering group sets measurable criteria: zero unexplained differences on the agreed rules for a set number of consecutive comparison days, completed general ledger trial balance agreement, and tested rollback steps. Select the Fineract business date that will be the first live day, and confirm the legacy system stops accepting postings for that date. Done when the criteria are signed by finance, operations and the risk owner, and the cutover runbook lists who makes the go or no-go decision.
Cut over and retire the source system after a hold period
On cutover day, freeze the legacy system, run the final extract at the agreed cut point, load any residual transactions, and rerun the full reconciliation before opening Fineract to live use. Keep the legacy system read-only through a defined hold period in case a reconciliation query or regulator request needs it. Retire it only after the hold period ends, and archive reconciliation reports and signed criteria as migration evidence. Confirm the length of the hold period with your compliance and records team, since it is set by your own policies.
How a parallel run is structured and what it compares
A parallel run works only if the team decides, before the window opens, which transactions are entered in both systems and which are entered once and then mirrored. Full duplicate entry means every client onboarding, disbursement, repayment, savings deposit, withdrawal and journal entry is keyed into the legacy system and into Fineract by the same people on the same day. That gives the strongest evidence, because each difference traces back to a single keyed event, but it doubles the operator workload and raises the chance that the duplicate entry itself introduces errors. The alternative is to run the legacy system as the book of record and compare extracts from both systems at fixed points, such as end of day or end of month. That is cheaper to operate, but it only tells you that balances disagree, not which transaction caused the gap. Many teams use duplicate entry for a limited set of high-volume or high-risk products and extract comparison for the rest. Confirm with your implementation partner and your own operations leads which mix you will use, and write it down per product.
The business date has to be held the same in both systems, or every difference will look like a timing problem. In Fineract, confirm how the business date is set for the window and whether your team will run the Close of Business job manually or on schedule. Ask the implementation team to list the batch and scheduler jobs that run during the window, including the Close of Business Day job, any scheduled interest posting and any job that alters loan schedules, and to confirm when each runs relative to your extract times. Differences are then logged and classified as timing (the same event posted on different dates), rounding (the same amount differing by minor units because of calculation order or precision), product rule (the configured product behaves differently from the legacy product) or data error (a migrated balance, client or rate was loaded incorrectly). Each classification needs a named owner. Product rule differences should go to the product design owner and data errors back to the migration lead, with the reconciliation sign-off recorded by a finance controller for each product and ledger.
What makes reconciliation and parallel run take longer or cost more
This table lists the factors that stretch a Fineract reconciliation and parallel run, marks whether each one is paid once during setup or keeps costing money through the parallel period, and shows what lowers the load. Use it to scope a quote, since most of the effort sits in the drivers that recur every reconciliation cycle. Ask any partner to price each driver separately so you can see which ones your own data and staffing actually raise.
| Driver | Why it changes effort | One-time or recurring | How to keep it down |
|---|---|---|---|
| Portfolio size | More loans and savings accounts mean more rows to match, more exceptions to investigate and longer extract runs on both systems. | Recurring, every reconciliation cycle | Reconcile by product and branch first, and limit full account-level comparison to exceptions. |
| Number of loan and savings products | Each product has its own fee, interest and schedule rules, so each needs its own comparison logic and sign-off. | One-time to design the mapping, recurring to rerun | Consolidate products before migration where the business allows it. |
| Interest methods that differ between systems | Where the legacy system computes interest or schedules differently, expected balances will not match Fineract's output without an explained adjustment. | One-time to analyze, recurring where adjustments are re-checked | Document each method difference with a worked example and agree tolerances with finance before the first run. |
| Number of GL accounts and feeding systems | Every account, and every system that posts journals into the ledger, adds a trial balance line and a mapping to verify. | Recurring, every close during the parallel period | Map feeding systems to GL accounts once and freeze the mapping for the parallel period. |
| Branches or offices in waves | Each wave needs its own cutover reconciliation, and inter-branch transactions during the transition must net out in both systems. | One-time per wave, with recurring checks for open waves | Keep wave size stable and reconcile each office to closure before opening the next. |
| Length of the parallel period | Every business day or month in parallel adds an extract, a comparison and an exception review on both systems. | Recurring for the full period | Agree the exit criteria and the number of consecutive clean cycles before the parallel run starts. |
| Staff performing manual comparison | Manual matching adds people-hours that scale with exceptions and cycles, and it depends on staff who also run the business. | Recurring, unless matching is automated | Automate the matching of routine items and assign a named owner for each exception category. |
| Automation built for extracts | Scripts that pull consistent, dated extracts from both systems cut manual work but need build, testing and maintenance effort. | One-time to build, recurring to maintain and rerun | Reuse the same extract scripts for every cycle and keep them under version control with tested queries. |
Common questions about reconciliation and parallel runs
How much effort does reconciliation and a parallel run add to a Fineract migration?
Reconciliation and parallel running add a distinct block of work on top of the data load itself, and its size depends mostly on portfolio volume, the number of products, the number of branches and how many ledger mappings the old and new systems need. Each reconciliation check has to be built, run, explained and repeated after every trial load. Cost comes from the people doing the work (your finance, operations and IT staff, plus any partner you hire) and from the time the old and new systems both need to be maintained. No effort figure is supplied for this work, so ask any partner to show the number of reconciliation checks, the number of trial loads and the staff hours behind each one in the written scope.
How long should a parallel period run before cutover?
The length of a parallel period is a business decision, not a platform setting. It should run long enough to cover the cycles that matter to your books, such as a full month-end close, interest postings, scheduled repayments and any batch processing that runs on a schedule. Fineract's Close of Business job can run for several hours on large deployments, so your parallel window should include several business days where that job runs under production-like volume. Confirm the length with your finance and risk owners, your regulator's expectations and your own test results, and write the exit criteria before the run starts.
What does the finance and operations team need to provide?
Reconciliation fails when finance and operations are not available to decide what a difference means. Expect to need:
- A named owner for the chart of accounts and each ledger mapping, who approves every posting rule
- Branch or operations staff who can explain loan and savings exceptions in the old system
- Access to historical statements, interest calculations and fee rules in the current platform
- Sign-off authority for each reconciliation result and for the cutover decision
Agree these responsibilities and dates in writing before the trial loads begin.
Can our own team run reconciliation and the parallel run without a partner?
Yes, many institutions with strong finance and data skills run reconciliation internally, and the Fineract API and its documentation give you the means to read balances and loan schedules. The questions to answer honestly are whether your team has done a parallel run before, whether it can rebuild loan and deposit calculations independently, and whether it can keep normal operations running while also supporting a parallel system. Partners are often used for the independent check, the scripts that compare counts and balances, and the documentation that auditors will review. Confirm internal capacity against the full list of checks before you decide.
How are differences found in reconciliation resolved?
Every difference should be traced to a cause and recorded before anyone changes data. Typical causes include rounding rules, interest day-count conventions, fee or charge timing, business date differences, and accounts that were closed or reopened during the move. Work from the highest level down: first counts of clients and accounts, then outstanding principal and interest per loan, then savings balances, then general ledger trial balances. Fix the mapping or load logic, rerun the affected trial load, and reconcile again. Keep a log of each difference, its cause, the fix and the approver, because that log is the evidence reviewers will ask for.
What should we ask a partner to include in a written scope?
A written scope should name the exact reconciliation checks, the source of truth for each, and the tolerance you will accept for each difference. Ask for:
- The list of client, account, loan, savings and ledger comparisons, with how each is produced
- The number of trial loads and the criteria that end each one
- The length and entry and exit criteria of the parallel run
- The difference log format and who signs each result
- The cutover and rollback steps, with owners
- Deliverables, dates and acceptance tests
DeployOpen agrees scope, deliverables and timelines in writing before work starts, so ask for these items to be spelled out in that document.
Does a parallel run prove the migration is compliant or audit ready?
No. A parallel run produces evidence about the data and the balances, but it does not produce an audit opinion or certification. Independent auditors and certification bodies make those judgments. Your reconciliation records, difference logs and sign-offs can support a compliance review, so design them to be retained and traceable. Ask your compliance lead which evidence they will need and confirm the retention requirements for your jurisdiction.
What usually goes wrong in Fineract reconciliation
Most failed Fineract cutovers do not fail in the load itself. They fail in the comparison, when balances drift, clocks disagree, or the test environment is quietly still open. Each card below names one of these risks and the check that prevents it.
Interest recalculation changes balances
Loading a loan with a balance and a schedule can trigger recalculation of interest or the schedule, so the principal and interest shown after load differ from the source system at cutover. Compare outstanding principal and interest per loan immediately after each load batch, before any repayments or business days run. Confirm with your implementation team how the chosen load path treats accrued interest and schedule regeneration, and record any delta with its cause.
Business date drift between systems
Fineract processes interest, accruals and posting against its business date, while the legacy system may use a different calendar or cutoff time. If the two systems do not agree on the as-of date, every balance comparison is comparing different days. Fix one as-of date for each comparison run, set it explicitly in both systems, and reject any comparison where the dates differ.
Batch jobs running during comparison
The Close of Business job can run for hours on large deployments and changes balances while you read them. A comparison extract taken during a run can mix pre- and post-batch states and produce false mismatches or hide real ones. Schedule comparison windows outside batch execution, confirm the batch has completed for the business date, and take the source and target extracts from the same closed state.
Unclear tolerance rules
Without written tolerances, teams either accept small differences without investigation or block cutover over rounding noise. Define tolerances per measure before the first run: exact match for client and account counts, and an agreed absolute amount for currency balances, with rounding rules stated per product. Every difference outside tolerance needs a named owner, a root cause and a recorded resolution.
Test environment left open
Parallel-run and reconciliation environments often copy production data while keeping the default development login or open endpoints. Fineract's default development credentials must be changed for any real deployment, and HTTPS should be enforced. Before loading real customer data into any test or parallel instance, confirm credentials are rotated, unused endpoints are closed, access is restricted to named staff, and the environment is covered by the same controls as production.
Counts reconciled without balances
Matching client and account counts can give false confidence while balances, currencies or product assignments are wrong. A loan can be present with the wrong product or an incorrect outstanding amount, and the count still matches. Treat counts as the entry gate, then reconcile balances per account and trial balance totals per ledger account before signing off the run.
How DeployOpen works on this
DeployOpen scopes reconciliation and parallel run as their own work package inside a Fineract migration, with reconciliation criteria agreed before any data moves. We build the comparison reports, run the parallel period against your chosen cutover controls, and document the evidence your team and auditors will review.
How we scope
- Agree the reconciliation criteria in writing: client and account counts, principal and interest per loan, savings balances and trial balance comparisons.
- Define which source extracts, business dates and tolerance rules apply to each comparison before the first test load.
- Confirm the parallel run length, the systems of record during the run and who signs off each reconciliation result.
How we build
- Build repeatable comparison scripts against the Fineract API and the legacy extracts, so every trial load produces the same reports.
- Test reconciliation against rehearsal loads and document each difference, its cause and the agreed resolution.
- Run the parallel period with both systems fed from the same daily inputs, logging every variance for review before cutover.
How we hand over
- Deliver reconciliation reports, variance logs and the signed-off cutover checklist as documentation your team can rerun.
- Walk your finance, operations and IT staff through how each report is produced and how to investigate a break.
- Provide evidence packs that support your own internal controls and independent audit, without claiming any audit outcome.
How we support
- Offer post-cutover reconciliation checks and variance investigation as a retainer, scoped in writing.
- Review reconciliation scripts again when Fineract versions, configuration or data sources change.
- Confirm support terms, response expectations and ongoing scope with your team before the engagement ends.
