Why replacing a legacy core in phases changes the Fineract build
A bank or lender running an ageing vendor core usually cannot switch it off in one weekend, so a phased replacement with Apache Fineract is the usual route. In that model the hard work is coexistence: two cores running side by side, one general ledger that must reflect both, and shared channels such as online banking, mobile, branch and card processing that must know which core holds a given customer or account. The Fineract install itself is the smaller task. Plan the build around the interfaces between the old and new cores, not around the Fineract server.
Fineract is headless. It exposes REST APIs and does not ship its own user interface, and the README points to the Mifos X web application as the front end used in its Kubernetes example. That means the Mifos X choice (or a different front end), channel integration, routing rules between cores, and reporting are build items the institution must own and fund. Ask each candidate partner to show, in writing, which screens staff will use for each product during the transition, how a customer's accounts are resolved when they straddle both cores, and who builds the reconciliation feed into the general ledger.
The Fineract 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. Treat that warning as a planning input. Confirm before signing whether the partner has run Fineract in production alongside a legacy core, what runbooks they will write for cutover and rollback per product, and how quarterly Fineract releases will be tested against the coexistence interfaces. Any figure for duration or effort should come from a written, scoped plan, not from the project.
Which requirements a phased core replacement must meet
This table maps the regulatory and platform requirements that a phased move onto Apache Fineract must satisfy to the build decisions they force. The regulations bind the institution, not the project, so each row names what the institution must evidence and what the implementation must provide for that evidence to exist. Read each row as a question to answer in the design phase, before the first product migrates.
| Requirement | Source | What it means for the build |
|---|---|---|
| Encryption of customer information in transit and at rest | 16 CFR 314.4 (FTC Safeguards Rule), applies to covered financial institutions | Encrypt Fineract API traffic, Mifos X sessions, channel connections and replication links during the parallel run. Confirm storage encryption for both cores and the migration staging area. |
| Multi-factor authentication for any individual accessing an information system | 16 CFR 314.4 (FTC Safeguards Rule) | Apply MFA to operator access to Mifos X, direct database access and admin consoles on both the legacy and Fineract sides. Confirm how service accounts used by channels are covered. |
| Change management procedures | 16 CFR 314.4 (FTC Safeguards Rule) | Each product configuration, accounting mapping and cutover step needs a documented approval path. Phased waves multiply the number of changes, so the change log must track which product or segment each change affects. |
| Logging of authorized user activity | 16 CFR 314.4 (FTC Safeguards Rule) | Enable audit logging in Fineract and the migration tooling, and retain logs for both cores during coexistence. Confirm that logs show who posted or reversed balances on each side of the cutover. |
| Annual penetration testing and vulnerability assessments at least every six months, absent effective continuous monitoring | 16 CFR 314.4(d)(2) (FTC Safeguards Rule) | Schedule testing before each migration wave goes live, not only once a year. Scope both the legacy core and the Fineract environment, and include the migration interfaces and the Mifos X front end. |
| Three-year record retention, with the first two years easily accessible, where broker-dealer records are in scope | 17 CFR 240.17a-4(b) (SEC), applies only where the institution is a broker-dealer | Confirm early whether any migrated records fall under this rule. If so, plan archive access for the legacy core after decommissioning and test retrieval of migrated transaction history. |
| PostgreSQL as the recommended Fineract database, with MariaDB and MySQL deprecated under FSIP-9 | Apache Fineract README and FSIP-9 proposal | Standardize the Fineract database on PostgreSQL from the start. Do not plan a MariaDB or MySQL target for new phases, because the official Docker image ships only the PostgreSQL JDBC driver. |
| Separate read, write and batch instances for cutover load | Apache Fineract platform documentation | Size one write instance, one batch instance and read instances on replicas, so that migration loads and end-of-day jobs do not compete with live channel traffic. Liquibase migrations run only on write instances, so schedule schema changes with that in mind. |
| Tenant ID handling for segregating migrated and legacy populations | Apache Fineract README (Fineract-Platform-TenantId header and tenants database) | Decide whether migrated segments sit in separate tenants or share one tenant. Confirm that every API client sends the correct tenant header, and test that a request cannot read another tenant's clients or accounts. |
Product-by-product or segment-by-segment: which phasing fits
A product-by-product phase moves one product family at a time, for example savings accounts first and consumer loans later. Customers may hold several products across both cores during the transition, so the team must decide which core owns each product and how a customer's total position is shown. Because Fineract is a headless application with REST APIs, every product migrated needs its own configured product definitions, accounting mappings and channel behavior before go-live.
- Parallel running: the legacy core keeps the products not yet moved, and Fineract runs the migrated products. Batch and end-of-day jobs must run on both sides in a defined order.
- General ledger feeds: each core posts to the general ledger for its own products. Opening balances for the migrated product must reconcile to the legacy ledger before cutover.
- Channel routing: online and mobile channels need a product-level routing rule so that requests for a migrated product go to Fineract and the rest go to the legacy core.
- Rollback path: rolling back usually means reverting one product's routing and reloading balances to the legacy core. Confirm whether any transactions posted in Fineract can be reversed or must be re-keyed.
Confirm with the business team how cross-product customer views, such as total exposure, will be produced during the transition.
A segment-by-segment phase moves a whole population at once, such as one branch network, one customer segment or one partner program. In Fineract's multi-tenant model, a partner or brand can be a tenant identified by the Fineract-Platform-TenantId header, which makes a tenant a natural migration unit for some institutions. Every product used by the segment must be ready, so the scope of each wave tends to be larger than in a product-by-product plan.
- Parallel running: the legacy core continues to serve the segments not yet migrated, and the segments already moved run on Fineract with their full product set.
- General ledger feeds: the ledger receives postings from both cores, so the chart of accounts and branch or entity codes must map cleanly across them.
- Channel routing: the front door must route by customer or branch identity, which means the routing logic depends on identity data that is itself being migrated.
- Rollback path: rolling back a segment returns that population to the legacy core. Confirm how customers who transacted in both cores during a wave will be reconciled.
Ask the implementation partner how segment boundaries are set, and whether any customer can be split across cores at all.
A hybrid plan moves a limited set of products to Fineract for a defined segment first, then extends both the product scope and the segment scope in later waves. The hybrid approach is often chosen when a pilot segment is small enough to contain risk, while the wider product set is still being built. It adds planning complexity because each wave is defined by two dimensions.
- Parallel running: the number of active product and segment combinations determines how many configurations, batch sequences and reconciliations must be maintained at any time.
- General ledger feeds: the ledger mapping must cover every combination in use, so mapping changes are controlled as a change-managed item for each wave.
- Channel routing: routing rules must evaluate both product and segment, and they should be tested for each combination before a wave goes live.
- Rollback path: define rollback per combination, not per project, so the team knows which legacy configuration remains valid at each step.
Ask for a written wave plan that lists every product and segment combination, its routing rule and its rollback action, along with the owner of each decision.
Which open-source platforms fit around Fineract during a phased move
A phased core replacement runs the old and new systems side by side for a period, so the surrounding platforms matter as much as the core itself. The cards below cover the core, its front end, and the adjacent components that a coexistence period often needs, each with the decision it forces and what to confirm before committing.
Apache Fineract as the target core
Fineract is the system of record for clients, loan and savings accounts, and real-time accounting in the target state. It is licensed under Apache-2.0 and the current stable release is 1.15.0. The project publishes official releases quarterly, so your team needs a written upgrade cadence and a test window for each one. Confirm which products, accounting rules and tenant model you need before the first migration wave, because those choices are costly to change later.
Mifos X as the web front end
Fineract is headless and ships without its own user interface, so staff screens during coexistence depend on a front end. The Fineract README names Mifos X as the web application used in its Kubernetes example. Treat it as a reference front end, not a finished branch product. Confirm with the project and your implementation partner which screens your branches, operations and credit teams need, how Mifos X connects to your Fineract version, and who maintains it after go-live.
Kill Bill for recurring billing
Kill Bill is an Apache-2.0 subscription billing and payments platform, and it fits only where recurring charges sit beside lending, such as a membership fee or an account service plan. Lending schedules stay in Fineract. Kill Bill must not become a second loan ledger. The current tagged build is killbill-0.24.22. Confirm the handoff of charge events into the general ledger, how refunds and failed collections reconcile, and whether your tax and audit needs are covered.
Hyperswitch for payment routing
During coexistence, some customers may pay through the old core's processors while others move to Fineract's channels. Hyperswitch is an Apache-2.0 composable payments platform that routes payments, payouts and tokenization across multiple providers, with self-hosted and SaaS options. It helps keep processor routing stable while accounts migrate. Its current version is v1.128.0. Confirm which processors and card vaults you need, where card data is stored, and the PCI scope your self-hosted deployment creates.
Odoo or ERPNext for the general ledger
An ERP can support general ledger, fixed asset and procurement work around Fineract, but it is optional. Odoo Community is LGPL-3.0 licensed, and ERPNext is GPL-3.0 licensed. Adding an ERP means a second financial system to reconcile against Fineract's own accounting, so keep the scope narrow and define which system owns the chart of accounts. Confirm the journal interface, the reconciliation process, and whether licensed Enterprise features, such as those listed on Odoo's editions page, are needed.
Rollout phases and the output each one produces
The sequence moves customer and loan data off the legacy core one product or segment at a time, and each step closes with a signed artifact that gates the next. The legacy core stays in service until retention and reconciliation checks have passed.
Agree scope and product mapping
The bank, its business owners and the implementation partner list every legacy product, fee, interest rule and accounting treatment, then map each one to a Fineract product or to a documented exception. Finance and risk sign the mapping before any build starts, and the list of products that will not move in the first wave is recorded with it. Done means a signed product mapping and a scope statement that names the segments in each phase.
Build tenants and environments on PostgreSQL
The team sets up Fineract tenants, environments and the database layer, using PostgreSQL because the Fineract README recommends it and deprecates MariaDB and MySQL under FSIP-9. Read, write and batch instances are configured through environment variables, and Liquibase migrations are run on the write instance, or separately with the liquibase-only Spring profile on Kubernetes. Done means a documented environment baseline and a configuration record that the operations team can rebuild from.
Run trial migrations and reconcile
Client, loan and savings data is extracted from the legacy core, transformed to the signed mapping and loaded into a non-production tenant. The team repeats the load until the row counts, schedules and balances match the source, and each run is compared with the general ledger opening balances. Done means a reconciliation report from the final trial with every difference either fixed or accepted in writing by finance.
Run both cores in parallel
For the phase in scope, the legacy core and Fineract process the same transactions for an agreed period, and channels continue to read from the legacy system until the results agree. Daily reconciliation reports compare balances, postings and end-of-day outputs between the two cores, and exceptions are assigned an owner and a closure date. Done means a parallel run report that finance and operations accept as evidence that Fineract produces the same results.
Cut over one product or segment
The team executes the cutover runbook for a single product or customer segment, moving channel routing, general ledger feeds and batch schedules to Fineract for that scope only. A rollback test is run in a rehearsal environment before the production window, and the rollback path is confirmed to restore the legacy product without data loss. Done means a completed cutover record with the runbook, the rollback test record and the first end-of-day reconciliation for the moved scope.
Repeat for each remaining phase
Each further product or segment goes through the same mapping, trial, parallel run and cutover gates, and lessons from earlier phases update the runbook before the next one. Channel integrations, reporting and the general ledger interface are rechecked for every phase because the set of live products changes. Done means a phase register showing which products run on which core, with the signed artifacts for each.
Decommission legacy products after retention checks
Before a legacy product is switched off, the bank confirms the records it must keep, including the retention periods set by its regulators and its own policy, and checks that archived data remains readable and searchable. Access to the legacy database is then restricted and the decommissioning is documented. Done means a retention check record and a decommissioning certificate signed by the data owner, which the bank should confirm with its regulators and auditors against its own obligations.
Evidence auditors and regulators ask for during a phased cutover
This table maps each evidence item an auditor or regulator is likely to request during a phased Fineract cutover to what it shows and the component that produces it. Read it as a checklist to agree with your assessor before the first migration wave. DeployOpen prepares this evidence, but independent auditors and regulators assess it and decide whether it is sufficient.
| Evidence item | What it shows | Component that produces it |
|---|---|---|
| Change approval records | Who approved each configuration, product, migration script and cutover step, and when | Ticketing or change management system, with release pipeline approvals and Fineract configuration exports |
| Access and MFA configuration | Which staff and service accounts can reach Fineract, the database and the migration tooling, and that multi-factor authentication applies to them | Identity provider, Fineract user and role configuration, database access policies and privileged access logs |
| Activity logs for authorized users | Who ran which API calls, batch jobs and direct database changes during parallel running and cutover | Fineract audit trail, application and gateway logs, database audit logging, centralized log store |
| Encryption configuration | That customer data is encrypted in transit over external networks and at rest, including backups and migration copies | TLS termination settings, database and volume encryption configuration, key management records |
| Penetration test and vulnerability assessment reports | Testing of the Fineract deployment, its APIs and channel integrations before go-live, with remediation tracking | Independent or internal test reports, scan outputs and a remediation register, to be confirmed against the scope agreed with the assessor |
| Reconciliation reports from parallel runs | That balances, schedules and postings in Fineract match the legacy core and the general ledger for each migrated product or segment | Trial migration outputs, reconciliation reports, variance logs and sign-off records from finance and operations |
| Retained records from the legacy core | That historical transactions, statements and business communications remain available for the retention period set by applicable rules | Archived legacy core extracts, retention schedule, restore tests; confirm the period with counsel and the regulator |
What do buyers ask before a phased Fineract migration?
How much does a phased core banking replacement on Fineract cost?
The cost is driven by scope, not by a license fee, because Apache Fineract is licensed under Apache-2.0. The Fineract README warns that a production deployment can be complex, costly and time-consuming, so the budget sits in product configuration, Mifos X or other front-end build, channel and general ledger integrations, parallel-run testing, infrastructure, regulatory reporting and ongoing support. Some of this is one-time work, such as the migration and integration build, and some recurs, such as infrastructure, support and quarterly upgrades. Ask any partner for a quote that lists each component separately, names who is paid for each, and states which items are fixed by the written scope and which depend on the number of products, channels and migration waves.
Is the Fineract license fee the main cost of replacing a core?
No. Apache Fineract carries no license fee under Apache-2.0, and the project's own README says production deployment is complex and may lead organizations to pay a vendor for deployment and maintenance. The larger costs are usually the work that makes a core fit one institution: mapping legacy products to Fineract products, reproducing accounting rules, building the channel and back-office integrations, and proving balances reconcile during coexistence. Compare the total cost of the open-source path against a licensed or SaaS core using the same scope list, including the parts you will still pay for after go-live.
How long does a phased migration to Fineract take?
The pace is set by the scope agreed in writing before work starts, not by the software. The main drivers are the number of loan and savings products, the number of channels and downstream systems that must be repointed, the number of migration waves (product by product or segment by segment), and how many reconciliation cycles the finance team requires before each cutover is approved. Ask a partner to show the wave plan, the criteria that close each wave, and the rollback point for each one. Any duration you are given should be traceable to those items, and you should ask which assumptions it depends on.
Can our own team run a phased Fineract migration without a partner?
Your team can own the decisions and the business sign-off, but a phased replacement needs several skill sets at once: Fineract configuration of products and accounting, PostgreSQL operations, integration engineering for channels and the general ledger, security hardening, and test automation for parallel runs. The Fineract documentation also describes read, write and batch instances with Liquibase migrations running only on write instances, which means the operating model must be designed before go-live. Ask whether the partner will transfer runbooks, configuration and knowledge to your staff, and which roles you must fill before the engagement starts.
How do we adopt Fineract's quarterly releases while two cores run side by side?
The Fineract README states that official releases are created quarterly, at the end of each quarter, following the ASF release policy, and that end-of-life releases are archived. During coexistence, pin the version used for each migration wave, test each new release against your products, integrations and reconciliation reports in a non-production environment, and schedule upgrades so they never fall inside an active cutover window. Confirm with the partner how Liquibase migrations are run on write instances during an upgrade, how rollback is handled, and who approves a release for production. The most recent stable release at the time of your plan is 1.15.0, published on July 14, 2026.
What must a partner show to prove a phased cutover is safe?
Ask for evidence at each wave, not only at the end of the program. A credible partner should show trial migrations, balance reconciliation between the legacy core and Fineract against the general ledger, reconciliation reports signed off by finance, and a documented cutover and rollback plan with named owners. Parallel-run results should be compared on balances, interest, fees and postings. For regulated institutions, also confirm how the records of each wave are retained and how access to migration tooling and databases is controlled and logged.
What does DeployOpen cover in a phased Fineract engagement?
DeployOpen plans, implements, customizes, integrates, hardens, backs up, upgrades, documents and supports self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For a phased Fineract replacement, that can include the product configuration, integration build, migration support, parallel-run testing and operational documentation, under a fixed scope agreed in writing before work starts. Ongoing support and upgrades are available as retainers. DeployOpen does not issue audit reports or certifications, and it does not publish a price list; a quote follows from the written scope.
Questions to ask an implementation partner before signing
Start with track record, because a phased core replacement is harder than a first deployment. Ask which Apache Fineract deployments the partner runs in production today, how many of them moved customers off a vendor core in stages, and whether any of those cutovers ran against a live general ledger while the old core still posted entries. Ask for the role they played in each one: architect, configuration lead, integrator or operator. Then ask which Fineract version each system runs. The Fineract project publishes official releases quarterly, and the current stable release at the time of writing is 1.15.0, so a partner should be able to say which release they standardize on and why. Confirm whether the partner will name reference contacts from comparable engagements under a confidentiality agreement.
Next, pin down who owns product mapping and accounting. Ask who writes the mapping from each legacy product to a Fineract product, including interest, fee, schedule and rounding rules, and who signs it off on the bank side. Ask how opening balances are tied to the general ledger, which reconciliation reports will be run before each wave, and who approves a variance. Ask how the partner sequences parallel runs and rollback: whether the old core stays authoritative for a segment until the new one matches it, how channel traffic is switched back, and how long the partner expects the legacy core to remain available for reversal. Also confirm whether Mifos X is in scope as the front end, or whether the bank's own channels will call the REST APIs directly. If Mifos X is in scope, ask which customizations the partner has made to it.
Finally, ask how the partner sizes read, write and batch instances and how they plan quarterly upgrades. The Fineract documentation recommends one write instance, one batch instance and multiple read instances on database read replicas for high load, and states that Liquibase migrations run only on write instances. Ask for the sizing method and the load test results behind it, and whether the partner runs Liquibase migrations separately using the liquibase-only Spring profile during upgrades. Ask how each quarterly release is tested against the bank's product configuration before adoption, and how long old releases stay supported in their plan. Ask what evidence they hand over at each wave: configuration exports, test records, reconciliation outputs, change records and runbooks. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications. Ask your auditors which evidence they need and confirm that the partner's handover covers it.
How DeployOpen scopes, builds and supports a phased core replacement
DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside the institution's own infrastructure. For a phased move off a vendor core, that means agreeing a written scope for each product or segment wave, then building and testing the Fineract environment, the channel and general ledger integrations and the cutover runbooks in the institution's own cloud accounts, data centers or air-gapped networks.
How we scope
- Written scope lists which products or customer segments move in each wave and which stay on the legacy core.
- Scope names the parallel-run period, reconciliation reports, cutover and rollback steps for each wave before work starts.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing; a quote follows from that written scope.
How we build
- Configure Fineract products, accounting rules and tenants to match the wave scope, with PostgreSQL as the database platform.
- Build the Mifos X or chosen front end, channel integrations and general ledger feeds, then test them against trial migrations.
- Set up read, write and batch instances, with Liquibase migrations controlled through a separate, documented run step.
How we hand over
- Documentation covers product configuration, integration interfaces, batch schedules, runbooks and rollback procedures for each wave.
- Reconciliation and cutover evidence is packaged so the institution's own risk, audit and compliance teams can review it.
- Knowledge transfer sessions prepare the institution's operations staff to run the platform before the legacy core is retired.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- Upgrade planning covers Fineract's quarterly release cycle and the adoption of new versions in a tested environment.
- Support scope, response expectations and service terms are confirmed in the written agreement rather than assumed.
