curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

Extra mortgage payment API

How much sooner a loan is paid off, and how much interest is saved, by paying extra each month or making one lump-sum payment.

POST https://api.curatedapi.com/v1/calc/finance/extra-payments

Runs a loan's schedule twice: once as agreed, and once with an extra amount on top of every payment, a single lump sum in a month you choose, or both. Extra money goes straight to the balance, so less interest builds up afterwards. The answer gives the new pay-off time and the interest saved.

Formula

each month: interest = balance × r, rounded; balance = balance + interest − (payment + extra); the last payment clears what is left
  • Check that your lender applies extra payments to principal and charges no prepayment penalty.
  • Amounts are plain numbers in any single currency; no currency conversion is done.

Inputs

Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).

InputTypeDescription
principal required decimal (string) The loan amount. Allowed: > 0 and <= 1000000000000000. Unit: currency.
annual_rate_percent required decimal (string) The annual interest rate. Allowed: >= 0 and <= 100. Unit: percent.
term_months required integer The loan term in months. Allowed: >= 1 and <= 600.
extra_monthly_payment decimal (string)
default 0
Extra paid with every monthly payment. Allowed: >= 0 and <= 1000000000000000. Unit: currency.
lump_sum decimal (string)
default 0
A single extra payment. Allowed: >= 0 and <= 1000000000000000. Unit: currency.
lump_sum_month integer
default 1
The payment number the lump sum is made with (1 is the first payment). Allowed: >= 1 and <= 600.
options.rounding half_even | half_up | half_down | up | down | ceiling | floor Rounding mode applied once to each result. Default half_even.
options.decimals integer Round results to this many digits after the decimal point.

Result

Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.

ResultTypeDescription
regular_paymentdecimal (string)The agreed monthly payment. Unit: currency.
months_to_pay_offintegerMonths until the loan is repaid with the extra payments.
months_savedintegerHow many months sooner that is.
interest_without_extradecimal (string)Total interest on the agreed schedule. Unit: currency.
interest_with_extradecimal (string)Total interest with the extras. Unit: currency.
interest_saveddecimal (string)The difference. Unit: currency.
total_paiddecimal (string)Everything paid with the extras: principal and interest. Unit: currency.

Examples

300,000 at 6.5% over 30 years with 200 extra a month

Requestcurl
curl https://api.curatedapi.com/v1/calc/finance/extra-payments \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": "300000",
    "annual_rate_percent": "6.5",
    "term_months": 360,
    "extra_monthly_payment": "200"
  }'
200 OKResponse
{
  "calculator": "finance/extra-payments@1",
  "result": {
    "regular_payment": "1896.20",
    "months_to_pay_off": 277,
    "months_saved": 83,
    "interest_without_extra": "382636.71",
    "interest_with_extra": "279186.52",
    "interest_saved": "103450.19",
    "total_paid": "579186.52"
  },
  "exactness": {
    "regular_payment": "exact",
    "interest_without_extra": "exact",
    "interest_with_extra": "exact",
    "interest_saved": "exact",
    "total_paid": "exact"
  },
  "precision": {
    "rounding": "half_even",
    "decimals": 2
  },
  "inputs": {
    "principal": "300000",
    "annual_rate_percent": "6.5",
    "term_months": 360,
    "extra_monthly_payment": "200",
    "lump_sum": "0",
    "lump_sum_month": 1
  },
  "formula": "each month: interest = balance × r, rounded; balance = balance + interest − (payment + extra); the last payment clears what is left",
  "references": [
    {
      "title": "Consumer Financial Protection Bureau: How does paying down a mortgage work?",
      "url": "https://www.consumerfinance.gov/ask-cfpb/how-does-paying-down-a-mortgage-work-en-1943/"
    }
  ],
  "warnings": []
}

References

Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.

Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.