Loan Management with French Amortization in Finper

The Loans module lets you track personal loans and mortgages with mathematical precision. Finper uses the French amortization method (constant monthly payment), meaning each scheduled payment covers the interest accrued on the outstanding principal plus a growing slice of capital repayment. The module maintains a full amortization table for every loan — combining your real payment history with a projected future schedule — and integrates directly with your Accounts and Transactions so that every payment automatically updates your account balance and spending history.

Data Model

Loan

Core loan record with terms and current state

LoanPayment

Individual payment entry (real, not projected)

LoanEvent

Rate or payment change (e.g. Euribor revision)

Loan Fields

Field	Type	Description
`name`	`string`	Descriptive label, e.g. `"Mortgage"`
`initialAmount`	`number`	Original principal; never changes after creation
`pendingAmount`	`number`	Remaining principal; decremented by each payment
`interestRate`	`number`	Annual nominal rate (TIN) as a percentage, e.g. `3.5` for 3.5%
`startDate`	`number`	Loan start date as Unix timestamp (ms)
`monthlyPayment`	`number`	Current scheduled monthly payment amount
`initialEstimatedCost`	`number`	Total projected cost computed at creation time (no extra payments)
`account`	`ObjectId`	Account from which payments are deducted
`category`	`ObjectId`	Expense category for auto-created payment transactions

LoanPayment Fields

Field	Type	Description
`date`	`number`	Payment date as Unix timestamp (ms)
`amount`	`number`	Total amount paid (interest + principal)
`interest`	`number`	Interest portion of this payment
`principal`	`number`	Capital repaid in this payment
`accumulatedPrincipal`	`number`	Total capital repaid up to and including this payment
`pendingCapital`	`number`	Remaining principal after this payment
`type`	`string`	`"ordinary"` (scheduled) or `"extraordinary"` (early repayment)

LoanEvent Fields

Field	Type	Description
`date`	`number`	Effective date of the change as Unix timestamp (ms)
`newRate`	`number`	New annual TIN (%) from this date onward
`newPayment`	`number`	New monthly payment amount from this date onward

Endpoints

Method	Path	Description
`GET`	`/api/loans`	List all loans for the current user
`POST`	`/api/loans`	Create a loan (auto-calculates `monthlyPayment` and `initialEstimatedCost`)
`GET`	`/api/loans/:id`	Full detail: loan data + stats + complete amortization table
`PUT`	`/api/loans/:id`	Edit loan fields
`DELETE`	`/api/loans/:id`	Delete a loan and all its payments and events
`POST`	`/api/loans/:id/pay`	Record an ordinary (scheduled) payment
`POST`	`/api/loans/:id/amortize`	Record an extraordinary (early capital) payment
`POST`	`/api/loans/:id/events`	Add a rate/payment change event
`POST`	`/api/loans/:id/simulate-payoff`	Simulate lump-sum payoff impact (no data modified)
`PUT`	`/api/loans/:id/payments/:paymentId`	Edit a recorded payment and recalculate the full chain
`DELETE`	`/api/loans/:id/payments/:paymentId`	Delete a recorded payment and restore the account balance

Amortization Math

Finper implements the French amortization (constant installment) method throughout. All amounts are rounded to 2 decimal places using Math.round(n * 100) / 100.

Monthly Rate

r = TIN% / 100 / 12

Example: TIN 3.6% → r = 3.6 / 100 / 12 = 0.003

Monthly Payment Formula

C = P × [ r(1+r)^n ] / [ (1+r)^n − 1 ]

Where:

C = monthly payment
P = outstanding principal
r = monthly rate (TIN% / 100 / 12)
n = remaining number of months

When the interest rate is zero the formula simplifies to C = P / n.

Amortization Table from `GET /api/loans/:id`

The detail endpoint returns a unified amortization table that merges real payment history with the projected future schedule. Each row indicates whether it is a real (isProjected: false) or projected (isProjected: true) payment. The projection is always anchored to the date of the last ordinary payment (not today’s date), so the projected schedule stays aligned with the actual payment calendar even after extraordinary payments.

Extraordinary Payments

Use POST /api/loans/:id/amortize to record an early capital repayment. You must specify both the amount and the mode:

reduceTerm — End Earlier
reduceQuota — Pay Less Each Month

The monthly payment stays the same; the loan simply ends sooner because more capital has been paid off.

curl -s -X POST http://localhost:3008/api/loans/64a1f2e3b4c5d6e7f8a9b0c1/amortize \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 5000,
    "mode": "reduceTerm"
  }'

Finper records the payment with interest: 0 and principal: amount, decrements pendingAmount, and keeps monthlyPayment unchanged. The next projected payment date is the same, but the table ends earlier.

The loan end date stays the same; the monthly payment is recalculated downward on the reduced principal.

curl -s -X POST http://localhost:3008/api/loans/64a1f2e3b4c5d6e7f8a9b0c1/amortize \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 5000,
    "mode": "reduceQuota"
  }'

Finper first calculates the remaining months using the inverse formula:

n = ceil( −log(1 − P·r / C) / log(1 + r) )

Then derives the new lower payment using the standard formula with the reduced principal and the same n:

newPayment = calcMonthlyPayment(pendingCapital, currentRate, n)

loan.monthlyPayment is updated immediately.

Rate Change Events

Use POST /api/loans/:id/events to record a change in interest rate or monthly payment — the typical use case being a variable-rate mortgage revised annually against Euribor.

curl -s -X POST http://localhost:3008/api/loans/64a1f2e3b4c5d6e7f8a9b0c1/events \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "date": 1704067200000,
    "newRate": 4.15,
    "newPayment": 812.50
  }'

Adding an event immediately updates the loan’s interestRate and monthlyPayment to the new values. The event itself is stored as an immutable history record, so the amortization table can correctly reflect different rates across different periods.

Payoff Simulator

POST /api/loans/:id/simulate-payoff lets you visualise the impact of making a one-time lump-sum payment without modifying any real data. Pass the hypothetical amount as lumpSum and Finper returns two fully projected scenarios side by side:

Scenario	What changes
Option A — Reduce Term	Same monthly payment, earlier end date
Option B — Reduce Quota	Same end date, lower monthly payment

curl -s -X POST http://localhost:3008/api/loans/64a1f2e3b4c5d6e7f8a9b0c1/simulate-payoff \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{ "lumpSum": 10000 }'

The response includes originalMonthsLeft, originalEndDate, and the full projected table for both options so you can compare total interest cost before committing.

Integration with Accounts

By default (addMovement: true), every ordinary and extraordinary payment automatically:

Deducts the payment amount from the linked account’s balance.
Creates an expense transaction in the linked category, giving you a full audit trail in your transaction history.

When you delete or edit a payment, these side effects are reversed or updated accordingly — the account balance is restored and the associated transaction is removed or adjusted.

Examples

Creating a Loan

curl -s -X POST http://localhost:3008/api/loans \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Home Mortgage",
    "initialAmount": 180000,
    "interestRate": 3.5,
    "startDate": 1672531200000,
    "monthlyPayment": 897.34,
    "account": "64a1f2e3b4c5d6e7f8a9b0c1",
    "category": "64a1f2e3b4c5d6e7f8a9b0c3"
  }'

Finper stores pendingAmount = initialAmount and computes initialEstimatedCost by projecting the full amortization schedule from scratch. Both calculated fields are returned in the response.

Recording an Ordinary Payment

curl -s -X POST http://localhost:3008/api/loans/64a1f2e3b4c5d6e7f8a9b0c1/pay \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "date": 1704067200000
  }'

Omitting amount uses the current scheduled monthlyPayment. Finper splits it into interest (pendingAmount × r) and principal (payment − interest), updates pendingAmount, deducts from the account balance, and creates an expense transaction — all in one call.

Get Started

Architecture

Modules

Operations

Loan Management with French Amortization in Finper

Data Model

Loan

LoanPayment

LoanEvent

Loan Fields

LoanPayment Fields

LoanEvent Fields

Endpoints

Amortization Math

Monthly Rate

Monthly Payment Formula

Amortization Table from `GET /api/loans/:id`

Extraordinary Payments

Rate Change Events

Payoff Simulator

Integration with Accounts

Examples

Creating a Loan

Recording an Ordinary Payment

Build docs developers (and LLMs) love

Get Started

Architecture

Modules

Operations

Documentation Index

​Data Model

Loan

LoanPayment

LoanEvent

​Loan Fields

​LoanPayment Fields

​LoanEvent Fields

​Endpoints

​Amortization Math

​Monthly Rate

​Monthly Payment Formula

​Amortization Table from GET /api/loans/:id

​Extraordinary Payments

​Rate Change Events

​Payoff Simulator

​Integration with Accounts

​Examples

​Creating a Loan

​Recording an Ordinary Payment

Build docs developers (and LLMs) love

Data Model

Loan Fields

LoanPayment Fields

LoanEvent Fields

Endpoints

Amortization Math

Monthly Rate

Monthly Payment Formula

Amortization Table from `GET /api/loans/:id`

Extraordinary Payments

Rate Change Events

Payoff Simulator

Integration with Accounts

Examples

Creating a Loan

Recording an Ordinary Payment