This API is useful to calculate the repayment plan, regarding the loan parameters assigned by the user.
This application will be ran by default on 8090 port, although the port number can be changed on application.yml file, that can be found on path "src/main/resources".
After assure that the application port is valid (that it is free to be used by this application), run the following command on project root folder:
mvnw clean install
This command will build the artifact. After build process finish, execute the command below to run the application:
java -jar target/repayment-0.0.1-SNAPSHOT.jar
If you see a message like this:
yyyy-MM-dd HH:mm:ss.SSS INFO 00000 --- [ main] c.c.repayment.RepaymentApplication : Started RepaymentApplication in X seconds (JVM running for X)
you will be able to perform the requests to the application.
In order to calculate a payment plan, an POST request should be performed to the method http://<projecturl>:<port>/generate-plan (e.g. http://localhost:8090/generate-plan) with the following body content structure:
{
"loanAmount": 5000,
"nominalRate": 5.0,
"duration": 24,
"startDate": "2018-01-01T00:00:01Z"
}
| Parameter | Type | Description |
|---|---|---|
| loanAmount | Float | The principal amount¹ |
| nominalRate | Float | Annual interest rate¹ |
| duration | Integer | Number of installments in months¹ |
| startDate | Date | Date of the first Disbursement/Payout |
All parameters are required and cannot be null.
¹ The numeric values should be greater than zero.
If the loan parameters in POST request was consistent, this operation will return a list with the repayment plan as below:
{
[
{
"borrowerPaymentAmount": "219.36",
"date": "2018-01-01T00:00:00Z",
"initialOutstandingPrincipal": "5000.00",
"interest": "20.83",
"principal": "198.53",
"remainingOutstandingPrincipal": "4801.47",
},
{
"borrowerPaymentAmount": "219.36",
"date": "2018-02-01T00:00:00Z",
"initialOutstandingPrincipal": "4801.47",
"interest": "20.01",
"principal": "199.35",
"remainingOutstandingPrincipal": "4602.12",
},
...
{
"borrowerPaymentAmount": "219.28",
"date": "2019-12-01T00:00:00Z",
"initialOutstandingPrincipal": "218.37",
"interest": "0.91",
"principal": "218.37",
"remainingOutstandingPrincipal": "0",
}
]
}
| Parameter | Type | Description |
|---|---|---|
| borrowerPaymentAmount | float | Borrower Payment Amount (principal + interest) |
| date | Date | Payment date |
| initialOutstandingPrincipal | Integer | Remaining value to be paid from the loan amount without interest |
| interest | float | Interest related on this payment |
| principal | float | Value without interest that will deduct the remaining loan amount |
| remainingOutstandingPrincipal | float | Remaining value to be paid after this payment (initialOutstandingPrincipal - principal) |
Some values are generated by a formula.
All these formulas are on CalculationRepaymentPlanService class.
The annuity amount has to be derived from three of the input parameters (duration, nominal interest rate, total loan amount) before starting the plan calculation. This value will be used on another following formula.
Annuity Payment = r(PV) / 1 - (1 + r) ^ n
Where:
| PV | Present value |
| r | rate per period - the nominal interest rate is an annual rate and must be converted to monthly before using in the annuity formula |
| n | Number of periods |
Interest = (Rate * Days in Month * Initial Outstanding Principal) / Days
in Year
e.g. first installment = (0.05 * 30 * 5000.00) / 360 = 20.83 € (with rounding)
In this project, for simplicity, we will have the following day convention: each month has 30 days, a year has 360 days.
Principal = Annuity - Interest
e.g. first principal = 219.36 - 20.83 = 198.53 €
if, calculated principal amount exceeds the initial outstanding principal amount, take initial outstanding principal amount instead (can happen in the very last installment)
Borrower Payment Amount(Annuity) = Principal + Interest e.g. first
borrower payment = 198.53 + 20.83 = 219.36 €
All this project is covered by unit tests. The jacoco library assures at least 99.9% of coverage. Therefore, all new methods, code lines, etc. that are added on this project should be covered by a test, otherwise the build process will be fail.