Floating interest rates in Apache Fineract

How floating interest rates work in Apache Fineract loans

A lender whose loan pricing follows a published base lending rate needs its loans to reprice when that rate moves, rather than holding a fixed rate set at disbursement. In Apache Fineract, that behavior is modeled with a floating rate scheme: a named set of rate periods that a loan product can reference. The scheme is the object your team configures and maintains, and the loan product is what ties individual loans to it. The legacy API documentation's Floating Rates section is the reference for the endpoints and fields, so confirm the exact request structure against the version you deploy before you design around it.

Each floating rate scheme has a unique name, an active flag, and one or more rate periods. The active flag controls whether the scheme is in use, and the rate periods hold the rate values that apply over the dates they cover. Only one scheme can be the base lending rate at any time, so a decision about which scheme carries that role is a governance decision as much as a configuration step. Decide who owns the base rate inputs, who may change them, and how the change is approved before the first product is linked, because every floating loan that references the base rate will be affected by that setting.

Teams should choose a floating structure when the lender's pricing is contractually or commercially tied to an external reference, and a fixed rate would either overcharge or undercharge borrowers as conditions move. Fixed rates remain simpler to explain, schedule and report, so the trade-off is operational: floating loans require a reliable process for entering new rate periods on time and for confirming which loans repriced. Before go-live, confirm with your product and risk owners how repricing applies to loans already in arrears, loans with paid installments, and loans in a restructured state, since those cases interact with the schedule and are covered in the sections that follow.

Which floating rate configuration fits which lending model

This table compares three ways to link Fineract loan products to a base lending rate: one shared base rate, separate schemes for distinct rate families, and product-level differentials on a fixed product rate. Read each row for the lending model it suits and the main cost of choosing it, then confirm the chosen design against the rate governance your credit committee expects.

Configuration	When it fits	Main trade-off
Single base lending rate for all products	One rate policy governs every floating product and one committee sets the rate for the whole lender	Only one scheme can be the base lending rate at a time, so a change moves every linked loan at once and products cannot follow separate rate families
Separate floating rate schemes per rate family	Products are priced off different reference rates, such as a retail rate and a commercial rate, and each family has its own review cycle	Each scheme needs its own rate periods and maintenance, and staff must confirm which scheme each product references before go-live
Product-level differential on a fixed product rate	The product carries a stable base rate and only a margin or spread changes with market conditions	Changing the differential means updating product configuration and confirming whether existing loans pick up the change, so test that behavior first
Floating rate with per-loan override	A small number of negotiated loans need a rate different from the product standard	Overrides are easy to create and hard to audit, so the reason and approver should be recorded in your own process

How to set up a floating rate scheme and link it to a loan product

This sequence takes a floating rate from design to a verified loan schedule in a Fineract test environment. Each step closes with a check that the rate applied to a loan matches the agreed design. Run every step in a non-production tenant first so that rate changes do not reach live accounts.

Document the rate design before configuring
The product owner works with finance and risk to record which loan products float, the source of the base lending rate, the differential for each product, the effective dates of each rate period, and who approves a change to the base rate. The output is a signed design sheet that lists every scheme, rate period, base designation and product link. The step is complete when each floating product has one named scheme and one agreed differential written down.
Create the floating rate scheme
In the test tenant, the configuration owner creates a floating rate scheme with a unique name and sets its active flag as the design sheet specifies. Use a naming convention that auditors can read, such as the rate type and the effective year. The Fineract legacy API documentation describes the floating rate fields, so confirm the exact request format against the version you run. The check is that the scheme appears in the floating rate list with the agreed name and active flag, and that a second scheme with the same name is refused.
Define rate periods with effective dates
The configuration owner adds one rate period for each interval in the design, entering the effective date and the rate value for each. Enter the periods in date order and confirm that no two periods overlap and no gap is left between them. The check is that reading the scheme back shows every period with the expected date and rate, in the expected order. Ask the vendor or project documentation how overlapping periods are handled before entering any that touch an existing boundary.
Designate the base lending rate
The configuration owner marks the scheme as the base lending rate. Fineract allows only one scheme to be the base lending rate at any time, so designating this scheme replaces any earlier base. Before making the change in a live environment, test how existing floating loans respond to a base change in the test tenant. The check is that the scheme shows as the base lending rate and that no other scheme carries the same designation.
Set product differentials
On each loan product that floats, the product administrator enters the differential the design sheet assigns to it. Differentials belong to the product, so two products that share one scheme can carry different spreads. Record the value exactly as the design sheet states it, including its sign and units. The check is that each product definition shows the differential that matches the design sheet, and that a product meant to stay fixed has no differential set.
Attach the scheme to loan products
The product administrator links the floating rate scheme to each loan product designed to float. A product without a linked scheme keeps its fixed rate, so every product on the design sheet needs an explicit decision. Attach the scheme to one product at a time and save each change before moving on. The check is that each floating product shows the linked scheme and that each fixed product shows none.
Verify the rate on test loan schedules
The tester creates a test loan on each linked product, with a disbursement date inside each rate period and one date that falls on a period boundary. The tester then compares the interest rate on each generated schedule with the value the design sheet predicts for that date and product. Keep the expected values in a table so the comparison can be repeated after any later change. The step is complete when every test loan matches its expected rate and the results are saved with the design sheet as evidence.

What to test when the base lending rate changes

Loans created or approved after the base rate changes should pick up the new rate, and the test should prove which rate was applied and when. Start by confirming which floating rate scheme is the single base lending rate at the moment of creation, because only one scheme can hold that role at any time. Then create loans on a product linked to the floating scheme, before and after the change, and compare the rate stored on each loan with the rate periods you configured.

Active base rate scheme: Confirm exactly one scheme is marked as the base lending rate before and after the change, and that the previous scheme was not left in that role.
Rate period boundaries: Create loans on the day of the change, the day before and the day after, and check which rate period each one falls into.
Approval versus disbursement date: Check whether the rate is fixed at approval, at disbursement, or at schedule generation, and test a loan approved before the change but disbursed after it.
Product defaults: Confirm the product still references the intended floating scheme and that no product was cloned with a stale link.
Inactive schemes: Confirm that an inactive scheme cannot be selected for new loans.

Keep the API responses for each test loan, the rate period list at the time of creation, and a dated record of who changed the base rate scheme.

Where floating rate setups go wrong in production

Floating rate problems rarely show up in configuration screens. They surface later, when a base rate change lands on the wrong loans, a differential is counted twice, or two products quote different rates for the same market. The cards below cover the risks we see most often and the control that prevents each one.

Two schemes claiming the base rate

Fineract allows only one floating rate scheme to be the base lending rate at any time, but a team can still create a second scheme and set it up as the base rate while the first remains active. Operators then read the wrong rate on new loans. Before go-live, check that exactly one scheme is marked as the base lending rate and that the change process retires the old scheme in the same step.

Overlapping or missing rate periods

A floating scheme carries rate periods with effective dates, and gaps or overlaps between them make the rate applied on a given day ambiguous. A missing period can leave interest accruing at an unexpected value or no rate at all for part of a loan term. Build a period calendar for each scheme, then test a loan that spans each boundary date before the scheme is used in production.

Differentials applied twice

A product differential is meant to sit on top of the base rate once. Teams sometimes add the differential in the scheme and again on the loan product, or repeat it when a loan is copied to a new product. The result is a rate that looks plausible on a summary screen but is wrong on the schedule. Compare the all-in rate on a sample loan with the value you calculated by hand for each product.

Rate changes not reaching active loans

Updating the base rate does not automatically reprice every open loan in the way a business might expect. Whether a loan picks up the change depends on how it was set up, when the change is effective, and whether the schedule is recalculated. Confirm with your own configuration which loans will move, on what date, and what the borrower will see in the schedule before any base rate change is entered.

Inconsistent rates across products

When several loan products reference the same market rate but each carries its own copy of the rate logic, they drift apart after the first revision. Staff then see different effective rates for the same borrower type depending on the product chosen. Keep one owner for the base rate definition, review product differentials against a single approved rate table, and run a regular comparison report across products.

Access control and audit for rate changes

A base lending rate change moves every floating loan linked to it, so who can create schemes, set the base rate and approve product changes matters as much as the rate itself. The cards below cover the access model, the separation of duties, transport security, authentication and the audit trail that together show who changed what and when.

Limit who can create rate schemes

Floating rate schemes are created and maintained through the Fineract REST API, so the first control is deciding which named users and roles may create a scheme, edit its rate periods or mark one as the base lending rate. Map those permissions to a small group in your identity provider and remove any shared or development accounts before go-live. Confirm in your own test environment which permission codes gate these actions, because permission names depend on the release you deploy.

Separate rate setters from product approvers

The person who sets a base rate should not also approve the loan products that depend on it. Without separation, one operator can change the base rate and approve the product differentials that take effect on the same day. Define two roles, one for rate maintenance and one for product approval, and record the approval step in your change process before the rate goes live. Test that a user holding only one role cannot complete the other step.

Enforce HTTPS for all API calls

Rate changes and loan requests travel as REST calls that carry credentials, so every client, batch job and integration should reach Fineract over HTTPS only. The Fineract documentation strongly encourages HTTPS only and documents SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. Confirm the setting on every write and read instance, and check that the reverse proxy or gateway in front of Fineract does not downgrade traffic.

Confirm authentication for your deployment

Fineract documents OAuth2 and HTTP basic authentication in its README, and its default development login must be replaced before any real use. Decide which method your integrations and operators use, and confirm the exact options and token handling for your release in the platform documentation and your own environment. Do not assume that a gateway or identity provider in front of Fineract replaces the application's own permission checks.

Keep an audit trail of rate changes

Confirm that every scheme creation, rate period change and base rate switch is recorded with the acting user, the time and the before and after values. Fineract's own records are only one layer, so also decide where API request logs go, how long they are kept and who can read them. Test the trail by making a change in a non-production tenant and tracing it from the log back to the user account, and agree the retention period with your compliance team.

Review the base rate change log

A rate change is only controlled if someone reviews it. Schedule a recurring check that compares the base rate history against the approved change tickets and flags any change without a matching approval. Include the loans that were re-priced by the change, so reviewers can confirm the effect matches the approved rate. Ask your implementation partner or internal team to document this review step as part of the operating procedure.

Questions teams ask before configuring floating rates

Is a single base lending rate enough for our loan products?

A single base lending rate is often enough when all floating loans move with one reference rate, but Fineract only allows one floating rate scheme to be the base lending rate at any time. If your products need different reference rates, such as a separate rate for a commercial product, you need a design for that before configuration starts, because the platform's base rate rule will not give you two active base rates. Confirm with your treasury or product owner which reference rates are in use and whose rate policy sets them. Differentials on each product then let you express the spread above or below the base rate, which covers most pricing differences without a second base rate. See the Fineract API legacy documentation for the floating rate object.

How much effort does floating rate configuration take, and who does it?

The configuration itself is small: creating rate schemes, rate periods and product links is a short task once the rate table is agreed. The effort sits in the decisions around it, including which products float, how differentials are set, how rate changes are dated against the business calendar, and how existing loans are treated. Your product owner and credit policy team usually make those decisions, while an engineer or implementation partner enters and checks the configuration. Ask any partner for a written scope that separates rate policy workshops, configuration, and test execution, so you can see who is paid for each part of the work.

What drives the length of a test cycle for a base rate change?

The main driver is the number of products and active loans linked to the base rate. Each floating product has its own differential, rate periods and schedule behavior, so each one needs at least one test loan that is run through the rate change and checked. Loans in different states, such as one in arrears or one already restructured, add more cases. Other drivers include how many rate change dates you need to test, whether your end-of-day batch must run for each date, and whether test data has to be prepared in a non-production environment that matches production. Ask for the test matrix in writing before agreeing on a timeline, since the number of products sets the size of the work.

Can our own team configure floating rates without a partner?

Yes, a team with Fineract administration experience can configure floating rate schemes and product links using the REST API and the platform's documentation. What usually needs outside help is the planning around the work, especially the testing of schedule changes and the review of how a rate change affects loans already in the book. Check whether your team has run Fineract's end-of-day process in a non-production environment, because rate changes depend on it. The Fineract platform documentation and the project's README note that a production deployment can be complex, so an internal team should confirm its capacity before taking on the full scope.

What must we supply before the configuration work starts?

You need to provide the written rate policy, the list of floating products, the reference rate table with effective dates, and the differential for each product. Sample loans are also important: provide a set of representative accounts covering each product, repayment frequency, and loan state, including loans in arrears and any already restructured. Also supply the holiday and working day rules that decide repayment dates, the test environment access, and a named approver for the rate table. Missing items usually cause rework during testing, so a partner should confirm the list in writing as part of the scope agreement.

What should we test when the base lending rate changes?

Test the rate change against each floating product, checking that the new rate applies from the correct effective date and that the differential is added or subtracted as designed. Check the repayment schedule of a sample loan before and after the change, the interest posted at the next run, and the behavior of loans that are early, on time, or overdue. Confirm that a loan already linked to the old scheme keeps its history, and that any closed or written-off loans are not affected. Include a test of a date that falls on a holiday, since it can shift the effective date. Record expected results before running each case so reviewers can compare them.

What control should exist before a new base rate goes live?

Use a four-eyes process: one person enters the new rate table in Fineract and a second person checks it against the signed rate notice before it is activated. Keep the approval, the effective date and the test evidence together so auditors and internal reviewers can trace each change. Fineract allows only one base lending rate scheme at a time, so the switch-over must be planned so the old scheme is replaced cleanly. Document a rollback step, and confirm with your auditor which evidence they expect. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors issue any audit report or attestation.

Does Fineract's floating rate feature fit a regulated lender's needs?

The feature suits lenders that price loans against one reference rate with product-level spreads, which covers many standard floating products. Lenders with several reference rates, complex rate caps, or regulatory disclosure rules may need additional design work or custom development, and should confirm each requirement against the current release notes. Ask your engineers to check the current Fineract release, which the project publishes quarterly, against your requirement list before committing to a design. The Apache Fineract project site lists the current stable release and the platform's documented features.

Official Fineract references for floating rates

Start with the Apache Fineract legacy API documentation for the floating rates endpoints. It covers the floating rate scheme object, including its unique name, its active flag and its rate periods, and it is the reference your team should use when mapping a base lending rate onto loan products. Read the floating rates section before you write any configuration script or test case, and confirm the exact request fields and response shapes against the version your environment runs, since the legacy documentation is organized differently from the current platform documentation.

Use the platform documentation for the wider loan model that a floating rate sits inside. It explains how loan products, interest settings and schedules fit together, which is the context you need to decide where a rate scheme affects a product and where it does not. Pay particular attention to how interest is calculated and recalculated, because a rate change only matters if the loan's schedule logic picks it up. Confirm those behaviors in a test environment rather than assuming them from the overview.

Treat the documentation as the starting point for your own verification, not the final word. Ask the implementation team to record which documentation version they worked from, and keep a short list of the endpoints and settings your build depends on. When you upgrade Fineract, re-check that list against the new release notes and documentation, because the behavior of rate schemes is one of the things an upgrade is most likely to change.

How DeployOpen works on this

DeployOpen scopes floating interest rates in Apache Fineract as a written, fixed-scope piece of work covering the rate schemes, base lending rate, product differentials and the test plan. The build runs in your own infrastructure, and the handover leaves your team able to change the base rate and rerun the checks.

How we scope

Confirm which loan products link to a base lending rate and which keep fixed rates.
Document the rate scheme names, rate periods and differential values each product will use.
Agree in writing who owns the base rate change process, approvals and effective dates.

How we build

Configure floating rate schemes with unique names, active flags and dated rate periods in a non-production tenant.
Set the single base lending rate and check that only one scheme holds that role at any time.
Run a regression suite covering schedules, accruals and repayments before and after each base rate change.

How we hand over

Provide written runbooks for changing the base rate, adding rate periods and reviewing affected loans.
Deliver the test scripts and expected results so your team can rerun them after each change.
Walk your operations and product staff through the configuration and the evidence it produces.

How we support

Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
Ongoing support, upgrades and continuous testing are available as a retainer.
Confirm with DeployOpen during scoping which Fineract release your rate configuration will be tested against.