Skip to content

Latest commit

 

History

History
159 lines (121 loc) · 4.88 KB

README.md

File metadata and controls

159 lines (121 loc) · 4.88 KB
Raw

Loan Calculation API

This API is useful to calculate the repayment plan, regarding the loan parameters assigned by the user.

How to start the application?

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.

Using API - Calculating a Repayment Plan

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 description

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.

Output

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",
        }
    ]
}

Parameters description

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.

Formulas

All these formulas are on CalculationRepaymentPlanService class.

Annuity

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 calculation

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

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)

Borrower Payment Amount(Annuity) = Principal + Interest e.g. first
borrower payment = 198.53 + 20.83 = 219.36 €

Unit Tests

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.