October 13, 2026 · 4 min read
Migrating a live portfolio to Fineract: the decision made before the first load
A migration is not decided by the loading tool but by two earlier questions: what gets migrated and where you cut. Getting either wrong surfaces the day accounting cannot reconcile the opening balance.
The first question anyone asks is which tool loads the portfolio. It is the last one that matters. A migration is defined by two earlier decisions — what gets migrated and where you cut — and getting either wrong goes unnoticed for weeks: it surfaces the day accounting cannot reconcile the opening balance against the ledger, by which point clients are already paying into the new system.
Balances or history: the decision that defines the project
Migrating balances only means creating each loan in Fineract as if it had been disbursed on the cut-off date, for the outstanding amount, over the remaining term. It is fast, predictable, and the balance reconciles by construction. What you lose is the past: a client three years into punctual repayment shows up as newly originated, and with them goes the arrears history that feeds classification, provisioning and any risk model you run.
Migrating full history loads the loan with its original disbursement date and then replays every repayment received. You keep the behaviour, but a requirement appears that catches everyone out: Fineract regenerates the repayment schedule from the product’s parameters, and that schedule has to match what the old system actually charged. To the cent. If the legacy core computed interest on a 360-day basis and the new product uses 365, every migrated loan is born with a difference nobody approved.
The decision is commercial, not technical, and there is a third path that is usually the right one: balances for the performing portfolio, history only where it is needed — loans in arrears, restructured ones, those in legal collection — which are typically under 10% and are exactly the ones a judge or a regulator can ask you for.
The cut-off and the window
The accounting cut-off and the operational one are almost never the same day. The accounting cut-off is the month close: the date whose balances you reproduce and reconcile against. The operational one is when you stop taking transactions in the old system. Days pass between them, and in those days the portfolio moves: repayments arrive, loans get disbursed, someone reverses last week’s transaction.
There are two ways to handle that gap. Freezing — no operations until the new system is live — is clean and expensive; it only works over a long weekend. Capture and replay — keep operating in the old system and apply the delta into Fineract afterwards — is the usual choice, and it requires the load process to be idempotent: it has to run twice without duplicating anything. Fineract’s externalId field exists precisely for this, and it is the difference between re-running a failed load calmly and having to empty the database and start over.
What your portfolio has that Fineract will not take
This phase always takes longer than estimated, because the problem records do not show up in testing: they show up three hours into the real load, failing by the batch. There are four usual suspects.
Restructured loans with no trace of the original, carrying a balance that derives from no disbursement. Rates outside the product’s range, usually an exception someone approved over the phone years ago. Impossible dates: a first repayment before the disbursement, or disbursements on weekends the new calendar will not accept. And duplicate clients, the same person under two identity numbers with a loan on each.
None of these is fixed by programming: each one is a business decision, and the mistake is discovering them mid-migration. Extract those exceptions six weeks earlier and hand them to operations as a list of cases to resolve.
The three figures that must reconcile before go-live
If one of them does not, you do not go live. There is no reasonable exception to this rule.
Principal outstanding by product against the ledger, by product and not in aggregate: two products with errors of opposite sign net to zero and hide both. Active loan count by branch, which catches batches that failed silently. And the sum of outstanding instalments against the old system’s projection, which is what reveals interest calculation differences once principal already reconciles.
That third one is the most often skipped and the most expensive, because correct principal with wrongly computed interest passes day-one review and surfaces at the first month close.
The rollback plan
Write it before you start, not when you need it. And make it answer a concrete question: what does rolling back on day three mean, when repayments already recorded in Fineract do not exist in the old system.
The honest answer is almost always that you do not roll back: you correct forward. Knowing that beforehand changes the preparation, because it forces a full rehearsal on a copy of production with the real reconciliation figures.