Every lending system has a repayment schedule at its core, and every team that builds one meets the same small problem: the numbers do not add up to the cent. This article covers loan amortization schedule calculation in Java, from the choice between annuity and equal principal to the formula, BigDecimal rounding, the last instalment that absorbs the difference, day-count conventions, and how to test the result.

It is an engineering article, not a description of any lender's product. Consumer credit law sets rules for how interest and the annual percentage rate are calculated and shown; we point to some of them below, but check the current rules in each country before you rely on them.

Annuity vs equal principal

There are two common ways to repay a loan in regular instalments:

MethodInstalmentPrincipal partInterest part
AnnuityThe same every periodGrows over timeFalls over time
Equal principalFalls over timeThe same every periodFalls over time

With an annuity, the borrower pays the same amount every month, and the share of principal in it grows as the balance falls. With equal principal, the principal part is fixed and the interest is added on top, so the first instalments are the largest.

The choice is not always the lender's. Romanian consumer credit law, for example, says that a loan can be repaid in equal instalments (annuities) or in decreasing instalments, and that the consumer has the right to choose (Art. 38 of OUG 50/2010, consolidated text published by ANPC). A schedule engine should support both.

The formula for a loan amortization schedule calculation in Java

For an annuity, the periodic payment A for a principal P, a periodic interest rate r, and n payments is the standard annuity formula:

A = P × r × (1 + r)^n / ((1 + r)^n − 1)      for r > 0
A = P / n                                   for r = 0

For a nominal annual rate paid monthly, r is the annual rate divided by 12. Each period, the interest is the open balance times r, the principal part is A minus the interest, and the balance falls by the principal part.

In Java, money calls for BigDecimal, and how you create it matters. The BigDecimal documentation warns that new BigDecimal(0.1) is not exactly 0.1, because 0.1 has no exact binary representation, and recommends the String constructor. Two more traps from the same page: divide without a rounding rule throws an ArithmeticException when the quotient has no terminating decimal expansion, such as 1 divided by 3; and equals compares the scale, so 2.0 and 2.00 are not equal, while compareTo treats them as the same number.

Java
static final MathContext MC = MathContext.DECIMAL128;
static final int CENTS = 2;

static BigDecimal annuityPayment(BigDecimal principal, BigDecimal rate, int n) {
  if (rate.signum() == 0) {
    return principal.divide(BigDecimal.valueOf(n), CENTS, RoundingMode.HALF_EVEN);
  }
  BigDecimal factor = BigDecimal.ONE.add(rate).pow(n, MC);         // (1 + r)^n
  return principal.multiply(rate, MC).multiply(factor, MC)
      .divide(factor.subtract(BigDecimal.ONE), MC)
      .setScale(CENTS, RoundingMode.HALF_EVEN);
}

MathContext.DECIMAL128 gives 34 significant digits with HALF_EVEN rounding, according to the MathContext documentation. Intermediate values keep that precision; only the payment is rounded to cents.

Rounding and the last instalment

A rounded payment repeated n times does not repay the principal exactly. Some cents remain, or are paid too much. The usual fix is to let the last instalment absorb the difference: it repays whatever balance is left, plus its interest.

Java
record Instalment(int number, BigDecimal payment, BigDecimal interest,
                  BigDecimal principal, BigDecimal balance) {}

static List<Instalment> schedule(BigDecimal principal, BigDecimal rate, int n) {
  BigDecimal payment = annuityPayment(principal, rate, n);
  BigDecimal balance = principal;
  List<Instalment> rows = new ArrayList<>();
  for (int k = 1; k <= n; k++) {
    BigDecimal interest = balance.multiply(rate).setScale(CENTS, RoundingMode.HALF_EVEN);
    BigDecimal principalPart = (k == n) ? balance : payment.subtract(interest);
    balance = balance.subtract(principalPart);
    rows.add(new Instalment(k, interest.add(principalPart), interest, principalPart, balance));
  }
  return rows;
}

For 10,000.00 at 12% a year over 12 months (r = 0.01), this gives eleven payments of 888.49 and a last payment of 888.47, with the balance at exactly 0.00. Equal principal has the same issue: 10,000.00 / 12 is 833.33 per month, and the last principal part is 833.37.

Which rounding mode? The RoundingMode documentation defines HALF_UP as rounding a tie away from zero ("commonly taught at school") and HALF_EVEN as rounding a tie to the even neighbour, so 2.5 becomes 2 under HALF_EVEN and 3 under HALF_UP. The same page notes that HALF_EVEN statistically minimizes cumulative error when applied repeatedly, and that it is sometimes called banker's rounding. Neither is right by default: the contract, the regulator, or the accounting policy may name one. Whatever the rule is, write it down, use it in one place, and test it.

Three other decisions belong in the specification, not in the code:

  • whether the interest is rounded per period (as above) or only the payment is rounded;
  • whether the difference goes to the last instalment or the first;
  • what happens when the last instalment would differ by more than a few cents, which usually means a bug.

Day-count conventions

Dividing the annual rate by 12 treats every month as equal. That is one convention among several. The common ones, as summarised in the day count convention article on Wikipedia:

ConventionInterest for a period
30/360Every month counts as 30 days, the year as 360
Actual/360Actual days in the period, divided by 360
Actual/365 FixedActual days in the period, divided by 365
Actual/ActualActual days, divided by the actual length of the year

Consumer credit law can limit the choice. The same Art. 38 of the Romanian OUG 50/2010 allows the monthly interest to be calculated either on the calendar year of 365 days (366 in a leap year) or with 30 days over 360.

With an actual-day convention, interest differs month by month, so an annuity payment fixed at the start no longer clears the balance exactly. The last instalment absorbs more, or the schedule is recalculated. A first period that is longer or shorter than a month, because the loan starts mid-month, has the same effect.

The annual percentage rate is a separate calculation

The annual percentage rate (APR) is not the nominal rate of the schedule. It is calculated from all payments and costs with a formula set by law. The Romanian rules, in Annex 1 of OUG 50/2010, assume a year of 365 days (366 in a leap year), 52 weeks, or 12 equal months of 30.41666 days, and require the result with at least one decimal, rounding the first decimal up when the second is 5 or more. In Germany, § 16 of the Price Indication Ordinance (PAngV) requires the effective annual rate (effektiver Jahreszins) to be calculated with the formula in its annex. The new EU Consumer Credit Directive (EU) 2023/2225 applies from 20 November 2026 and sets out the APR calculation in its Annex III, so national rules may change; check the version in force.

Testing a schedule

A schedule is a good candidate for tests that check rules rather than single values:

  • The principal parts add up to the principal, to the cent.
  • The balance after the last instalment is exactly zero.
  • Every annuity payment is equal, except the last, and the last differs by a bounded amount.
  • The interest parts add up to the total interest shown to the borrower.
  • A zero rate, a single instalment, and a very small principal all work.

Add a few golden schedules, calculated independently and reviewed by someone from finance, and compare to the cent. Run the rule-based checks over many generated combinations of principal, rate, and term. Rounding bugs tend to appear in one case out of thousands, not in the example from the specification.

How we can help

We build lending software with loan servicing and repayment schedules: annuity and equal-principal schedules, early repayment, changes over the life of the loan, and the tests that keep every cent accounted for.