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
- Version 1
- MCP tool
calc_finance_extra_payments - Try it in the browser
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).
| Input | Type | Description |
|---|---|---|
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.
| Result | Type | Description |
|---|---|---|
regular_payment | decimal (string) | The agreed monthly payment. Unit: currency. |
months_to_pay_off | integer | Months until the loan is repaid with the extra payments. |
months_saved | integer | How many months sooner that is. |
interest_without_extra | decimal (string) | Total interest on the agreed schedule. Unit: currency. |
interest_with_extra | decimal (string) | Total interest with the extras. Unit: currency. |
interest_saved | decimal (string) | The difference. Unit: currency. |
total_paid | decimal (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
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"
}'
{
"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.