THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Migrated over from MifosForge - last edit on October 7, 2015.
Overview
Many Banks and Financial Institutions use lending rates that are linked to the Base Lending Rates defined by the Central Bank of the country. Home Loans and other longer term loans are usually given out by banks/financial institutions at floating interest rates - where the interest rate applicable for the loan is linked to the interest rate set by the Central Bank and is periodically revised by the Central Bank. The interest rate applicable for the loan, can change during the tenure of the loan. The loan may start off as a 10% loan and may get revised to 10.5% after a period of time and can even be revised downwards (for example: 9.5%) depending on guidelines issued by the Central Bank from time-to-time.
Background and strategic fit
This feature will bring Mifos X closer to a true bank and real-life financial institutions and not restrict its usage to micro-finance scenarios where interest rates are fixed during the tenure of the loan account.
Requirements/User Stories
| # | Title | User Story | Importance | Notes |
|---|---|---|---|---|
| 1 | Set Base Lending Rate | As an operations manager I wish to set the Base Lending Rate for various periods | Must have | |
| 2 | Define Floating Interest Rate Loan Product | As an operations manager I wish to define a loan product with the additional parameters relevant for floating interest rates.
| Must have | |
| 3 | Open Floating Interest Rate Loan Account | As a loan officer, I wish to create a loan account for a loan product which has the additional parameters relevant for floating interest rates set. | Must have | |
| 4 | Service a Floating Interest Rate Loan Account | As a loan officer, I wish to manage a Floating Interest Rate loan account that would have different interest rates applicable for different periods of time during it's term | Must have |
Business Rules
a) If Floating Interest Rate is false, then changes to Base Lending Rate will not impact existing loans, but will impact new loans (depending on the disbursal date of the loan)
b) Floating Interest Rate will be applicable only for Diminishing balance based loans with interest recalculation.
c) For a loan with Floating Interest Rate, Interest for each instalment will be computed based on floating interest rate applicable on the instalment due date.
d) If the Floating Interest Rate change OR the Base Lending Rate change occurs between two installments, then the interest for the next instalment will be calculated based on the exact date of change. For example:
10th Installment – 12th March 2015
11th Installment – 12th April 2015
Base Lending Rate is 9% per annum
On 1st April Floating Interest Rate changes from +1.5% to +1.75%
Outstanding balance is 20,000 on 12th March 2015. Interest will be computed as follows:
Interest till 1st April = (20,000 * 10.50% * 20/365) + (20,000 *10.75% * 11/365)
i.e. interest computed with old rate for 20 days and then interest computed with new rate for the remaining 11 days.
e) Audit Trail has to be maintained and displayed to user for:
- Base Lending Rate changes
- Loan Product Interest Rate changes
- Account Level Interest Rate changes
Attributes
Attributes for Base Lending Rate:
| Attribute | Description | Notes |
|---|---|---|
| From Date | Start Date for this Base Lending Rate to be applicable | Inclusive of this date |
| To Date | End Date till when this Base Lending Rate will be applicable | Inclusive of this date |
| Base Lending Rate | Base Lending Rate applicable for this period (expressed in percentage) | Format: 99999.99999 |
Attributes for loan products:
| Attribute | Description | Notes |
|---|---|---|
| Interest rate linked to Base Lending Rate? | Boolean value that describes if this loan product is linked to the Base Lending Rate of the bank | True / False. This field is applicable for non-floating interest rate loans too. Default False. |
| If True, then rate above (or less) the Base Lending Rate | Interest rate differential – For example +1.5% would mean 1.5% above the Base Lending Rate | This can be a range, as it exists in Mifos today (min, default and max) This field is applicable for non-floating interest rate loans too. |
| Floating Interest Rate? | Boolean value that describes if this loan product has a floating interest rate or not. | True / False Default False. |
If yes, then allow period based interest rates to be captured. Note: This could be a phase 2 enhancement as I have not encountered any customer specifically asking for this level of flexibility. Needs to be validated if actual banks also want this level of flexibility in the product definition. | Interest rate differential for different periods. For example: a) 01-Jan-2009 to 10-Apr-2012 Interest differential is +1.5% b) 11-Apr-2012 to 21-Jun-2014 Interest differential is +1.75% c) 22-Jun-2014 to <null> Interest differential is +1.25% | Validations: There should not be any gaps in the periods. If “Interest rate linked to Base Lending Rate” is set to true, then an interest rate differential is provided. Else, actual interest rates may be given by user, instead of an Interest Rate Differential |
Security and Permissions
The following new permissions need to be added:
SET_BASE_LENDING_RATE
Mifos Functionality Enhancements
New Screens
New screens for maintaining (listing, adding, editing and deleting) period-wise Base Lending Rates. This will have the following fields:
From Date
To Date
Base Lending Rate (99999.99999%)
Also, screen needed to view Base Lending Rate modifications with date-time when the change was done and the user who did this change.
Changes to Existing Screens
a) Loan Product screen to be modified to collect the additional four attributes.
b) Also, a link needed to view Loan Product Interest Rate modifications with date-time when the change was done and the user who did this change.
c) For loans that are linked to Base Lending Rate, Loan Account screen to be modified to display the Base Lending Rate and the Differential Interest Rate that is applicable for the loan
d) For loans that have Floating Interest Rate, Loan Account screen to be modified to display the period-wise - Base Lending Rate and the Differential Interest Rate that is applicable for the loan. It would be logical to show this in a separate tab on the loan account page.
Changes/Enhancements to Batch Jobs
None specific to the Base Lending Rate or Floating Interest Rates.
Interest accrual, interest recalculation jobs should automatically use the business rules mentioned above for interest calculations.
Changes/Enhancements to Accounting Entries
None
User interaction and design
TBD
Exception Handling
The following exception scenarios are to be handled:
a) Gaps identified in periods when providing Base Lending Rates – “There is no Base Lending Rate provided for the period of 01-Jan-2014 to 20-Jan-2014”
b) Gaps identified in periods when providing Floating Interest Rates” for a loan product – “There is no Interest Rate provided for the period of 01-Mar-2014 to 05-Mar-2014”
c) When creating or approving a loan account, Mifos is unable to find an interest rate relevant for the loan’s disbursal date – “No relevant Base Lending Rate or Floating Interest Rate provided for the disbursal date of 01-Mar-2001”
Reporting
No specific new reports needed for this functionality.
APIs
New APIs needed for maintaining the Base Lending Rates
New API needed for fetching audit trail for changes to Base Lending Rates
Loan Product APIs to be modified for accepting new parameters relevant for Base Lending Rate and Floating Interest Rate
Loan Product APIs to return the audit trail (when needed) of interest rate changes
Loan Account APIs to be modified for getting Base Lending Rate and getting the Floating Interest rates that are applicable for this
Loan Product APIs to return the audit trail of interest rate changes
Notes
For existing loan products and loan accounts the following will be the default values:
Interest rate linked to Base Lending Rate? - False
Floating Interest Rate? – False
This will ensure that existing loan products and loan accounts will not be impacted.
Questions
Below is a list of questions to be addressed as a result of this requirements document:
| Question | Outcome |
|---|---|
Should Base Lending Rate and Floating Interest Rate be provided for the same period? For example: if Base Lending Rate is given as yearly rate, can Floating Interest Rate be provided as a monthly rate? Will there be any conflicts during calculations? | |
| Is it ok to keep the floating interest linked to the disbursal date (and not link it to the loan application submission date and loan approval date)? | Yes, Should be linked to disbursal date (DBH) |
| Should floating interest rate be application for products that do not support Interest Recalculation? If yes, need to get list of exact scenarios to be supported. | |
| Once a loan account starts using a floating interest rate and repayments are already made, then it is planned to not allow any modification prior to the repayment date for Base Lending Rate and loan product level Floating Interest Rate. Is this ok? | yes, the only time it would be feasible to make a modification prior to repayment date is in the case of error correction. this would then be done thru journal entries. (DBH) |
Out of Scope
TBD
Detail Design for Implementation
Defining Floating Interest Rates
API
New APIs would be exposed thru which Floating Interest Rate schemes can be created/updated/deleted(inactivate).
| METHOD | URL | Purpose |
| GET | /mifosng-provider/api/v1/floatingrates | List floating interest rates |
| POST | /mifosng-provider/api/v1/floatingrates | Create new floating interest rate |
| GET | /mifosng-provider/api/v1/floatingrates/{floatingrateid} | Get details of specific floating interest rate |
| PUT | /mifosng-provider/api/v1/floatingrates/{floatingrateid} | Edit specific floating interest rate |
JSON Data exchange format:
{
floatingRates: [
{
floatingRate: {
id: [long],
name: [string],
isBaseLendingRate: [boolean],
isActive: [boolean],
ratePeriods:[
{
ratePeriod: {
id: [long],
fromDate: [date],
interestRate: [decimal],
interestRatePeriodEnum: [smallint],
isDifferentialToBaseLendingRate: [boolean],
isActive: [boolean]
}
}
]
}
}
]
}
Types of Floating Rates
Any number of floating rate schemes can be created. But they would fall under one of the 3 types explained below. An example illustration is given far down below.
Base Lending Rate
- This is a unique floating rate scheme identified by isBaseLendingRate attribute
- There can be only one Base Lending Rate for an organisation at any given time
- Will have its own period and interest definition
- Loan Products that wants to re-use Base Lending Rate periods with only a differential rate added on top of it should link to this type of scheme
Differential to Base Lending Rate
- Floating rate scheme dependent on Base Lending Rate
- Can define its own Floating rate periods (independent of Base Lending Rate)
- Interest rate specified is differential of Base Lending Rate as of start date of the given period (attribute ratePeriod.isDifferentialToBaseLendingRate will be true)
- Cannot exist without a Base Lending Rate already defined
- Loan Products that wants to use a differential rate on top of prevailing Base Lending Rate but with their own time periods should link to this type of scheme
Independent Floating Lending Rate
- Floating interest rate scheme with own rate and period
- Not dependent on Base Lending Rate
- floatingRate.isBaseLendingRate and ratePeriod.isDifferentialToBaseLendingRate attributes will be false
- Loan Products that wants to define an independent floating rate and time periods should link to this type of scheme
UI Screens
- New Button under "Admin > Products" by name "Floating Interest Rates"
- New screen that lists all the "Floating Interest Rates" schemes along with "Create" button.
- New screen to Create Floating Interest Rate
- New Screen to View Interest Rate and Applicable Periods along with "Edit" button
- New Screen to Edit Floating Interest Rate
Restrictions
- Interest Rate periods can be added/updated/modified only with a future start date
- Only one Base Lending Rate type of scheme at any given time
- Differential to Base Lending Rate type cannot be created without Base Lending Rate already defined
- interestRatePeriodEnum attribute for Differential to Base Lending Rate type will be same as Base Lending Rate
- Base Lending Rate cannot be inactivated when there is any Differential to Base Lending Rate type active
DB changes
Following new tables would be added
| m_floating_rates | ||
| field_name | field_type | Contraints |
| id | long | not null auto increment |
| name | varchar[200] | not null |
| is_base_lending_rate | bit | not null default false |
| is_active | bit | not null default true |
| created by | bigint | not null |
| created date | datetime | not null |
| modified by | bigint | not null |
| modified date | datetime | not null |
| m_floating_rates_periods | ||
| id | long | not null auto increment |
| floating_rates_id | long | not null |
| from_date | datetime | not null |
| interest_rate | decimal | not null |
| interest_rate_period_enum | smallint | not null |
| is_differential_to_base_lending_rate | bit | not null default false |
| is_active | bit | not null default true |
| created by | bigint | not null |
| created date | datetime | not null |
| modified by | bigint | not null |
| modified date | datetime | not null |
Defining a Loan Product
API
Following additional attributes will be added to /mifosng-provider/api/v1/loanproducts list/add/update APIs
| Sl | Attribute | Type | Definition |
| 1 | isLinkedToFloatingInterestRates | boolean | Identifies a loan product is linked to floating rates |
| 2 | floatingRateId | long | Floating rates scheme to be followed |
| 3 | interestRateDifferential | decimal | Differential on top of rate as derived by Floating rate scheme Basically "Loan Product Base Rate" is derived based on this differential |
| 4 | minDifferentialLendingRate | decimal | Min differential w.r.t "Loan Product Base Rate" while providing loans |
| 5 | defaultDifferentialLendingRate | decimal | Default differential w.r.t "Loan Product Base Rate" while providing loans |
| 6 | maxDifferentialLendingRate | decimal | Default differential w.r.t "Loan Product Base Rate" while providing loans |
| 7 | isFloatingInterestRateCalculationAllowed | boolean | If true, loan can be given with floating interest calculations If false, interest rate for the loan is fixed as per the rate derived as on loan application date |
UI
Loan product create/edit screens will have following additional fields
- A checkbox "Is Linked To Floating Interest Rates" under section "Terms"
- If unchecked, existing "Nominal interest rate" attributes would be visible and captured
- If checked, attributes 2-6 defined above will become visible and be captured
- A checkbox "Is Floating Interest Rate Calculation Allowed" under section "Interest Recalculation"
- Only allowed to check if Interest Method is Declining Balance
DB Changes
New table will be added
| m_product_loan_floating_rates | ||
| id | long | not null auto increment |
| loan_product_id | long | not null |
| is_linked_to_floating_interest_rates | bit | not null default false |
| base_lending_rates_id | long | not null |
| interest_rate_differential | decimal | not null default 0 |
| is_floating_interest_rate_calculation_allowed | bit | not null default false |
| min_differential_lending_rate | decimal | not null default 0 |
| default_differential_lending_rate | decimal | not null default 0 |
| max_differential_lending_rate | decimal | not null default 0 |
Defining Loan
API
Following additional attributes will be added to /mifosng-provider/api/v1/loans view/create/edit APIs
| Attribute | Type | Description | Restrictions |
|---|---|---|---|
| interestRateDifferential | decimal | Interest Rate differential applicable to loan application w.r.t "Loan Product Base Rate" | Should be within min/max rage as defined in loan product |
| isFloatingInterestRate | boolean | Is floating interest rate calculation applied for the loan? If false, flat interest rate as applicable on loan application date If true, interest rate as applicable from period to period | Only allowed if isFloatingInterestRateCalculationAllowed is true at loan product definition |
UI
Loan create/edit screens will have following attributes
- "Nominal interest rate" field will be replace with "Interest Rate Differential" field in case loan product is linked to Floating Interest Rates
- A checkbox "Is Floating Interest Rate Loan" will be added in case loan product is linked to Floating Interest Rates and isFloatingInterestRateCalculationAllowed is allowed for the loan product
DB Changes
Following fields added to m_loan
| m_loan | ||
| is_floating_interest_rate | bit | not null default false |
| interest_rate_differential | decimal | nullable |
Example Illustration
Below table illustrates what will be the applicable interest rates for any given date period.
Loan Product Differential Rate
(A) | Loan Application Differential Rate
(B) | Date
(C) | Base Lending Rate in % (Rates defined as part of "Base Lending Rate type") (D) | Floating Interest Rate (Loan product Linked to "Base Lending Rate") (E)=(A)+(B)+(D as of date) | Differential to Base Lending Rate % (Rates defined as part of "Differential to Base Lending Rate type") (F) | Floating Interest Rate (Loan product Linked to "Differential to Base Lending Rate type") (G)=(F)+(E as of the period start date) |
| 2 | 1 | 01-10-2010 | 8 | 11 | 2 | 13 |
| 10-10-2010 | ||||||
| 16-10-2010 | 9 | 12 | ||||
| 31-10-2010 | 7 | 10 | 1 | 11 | ||
| 10-11-2010 | 2 | 12 | ||||
| 15-11-2010 | 6 | 9 | ||||
| 30-11-2010 | 8 | 11 |