[−][src]Function finance_solution::payment

pub fn payment<P, F>(
    rate: f64, 
    periods: u32, 
    present_value: P, 
    future_value: F, 
    due_at_beginning: bool
) -> f64 where
    P: Into<f64> + Copy,
    F: Into<f64> + Copy, 

Returns the payment needed at the end of every period for an amortized loan.

Related functions:

  • To calculate the payment needed at the end of each period and return a struct that shows the interest, the formula, and optionally the period-by-period values use payment_solution.

In the typical case where there's a present value and the future value is zero, and the payment is due at the end of the period, the formula is:

payment = ((present_value * (1 + rate)periods) * -rate) / ((1 + rate)periods - 1)

or with the more commonly used variables:

pmt = ((pv * (1 + r)n) * -r) / ((1 + r)n - 1)

Often the payment is shown as A and the present value is P for principal.

If there's a future value and the present value is zero, the formula is:

payment = (future_value * -rate) / ((1 + rate)periods - 1)

or:

pmt = (fv * -r) / ((1 + r)n - 1)

If both present value and future value are nonzero the formula is:

payment = (((present_value * (1 + rate)periods) + future_value) * -rate) / ((1 + rate)periods - 1)

or:

pmt = (((pv * (1 + r)n) + fv) * -r) / ((1 + r)n - 1)

If the payment is due at the beginning of the period, the only difference is that the payment is divided by (1 + rate). In our formulas this means multiplying the denominator by (1 + rate) so in the typical case where there's a present value and the future value is zero, the formula is:

payment = ((present_value * (1 + rate)periods) * -rate) / (((1 + rate)periods - 1) * (1 + rate))

or with the more commonly used variables:

pmt = ((pv * (1 + r)n) * -r) / (((1 + r)n - 1) * (1 + r))",

This is nearly the same formula as the one for payments due at the end of the period. The relationship between the two formulas is that:

payment_due(x) = payment(x) / (1 + rate)

Thus the payment is slightly smaller if it's due at the beginning of the month since the principal is paid down a bit faster.

If there's a future value and the present value is zero, the formula is:

payment = (future_value * -rate) / (((1 + rate)periods - 1) * (1 + rate))

or:

pmt = (fv * -r) / (((1 + r)n - 1) * (1 + r))

If both present value and future value are nonzero the formula is:

payment = (((present_value * (1 + rate)periods) + future_value) * -rate) / (((1 + rate)periods - 1) * (1 + rate))

or:

pmt = (((pv * (1 + r)n) + fv) * -r) / (((1 + r)n - 1) * (1 + r))

Arguments

  • rate - The interest rate per period, expressed as a floating point number. For instance 0.01 would mean 1% interest per period. The rate must match the period type. For instance if the periods are months and we're starting with an annual interest rate, the rate must be divided by 12 when calling the function as shown in the example below. The rate often appears as r or i (interest) in formulas.
  • periods - The number of periods such as quarters or periods. Often appears as n or t where t typically implies years.
  • present_value - In the case of an amortized loan this is the the principal. It may appear as pv in formulas, or C for cash flow or P for principal. Assuming that the future value is zero, the payment will be negative if the present value is positive and vice versa.
  • future_value - The value at the end of the last period. For a typical amortized loan this will be zero. It appears as fv in formulas.
  • due_at_beginning - True if the payment is due at the beginning of the period. Typically the payment will be due at the end of the period so this will be false.

Panics

The call will fail if rate is less than -1.0.

Examples

A simple amortized loan with the payment due at the end of the month.

// The loan will be paid off in five years.
let years = 5;

// The interest rate is 10% per year. Each period is one month so we need to divide the rate
// by the number of months in a year.
let rate = 0.10 / 12.0;

// Each period is one month so we need to multiply the
// years by the number of months in a year.
let periods = years * 12;

// The principal is $10,000.
let present_value = 10_000;

// The loan will be fully paid off by the end of the last period.
let future_value = 0;

let due_at_beginning = false;

let pmt = payment(rate, periods, present_value, future_value, due_at_beginning);
dbg!(pmt);

// The payment is $212.47/month. Since the principal/present value was positive the payment is
// negative.
assert_rounded_4(pmt, -212.4704);


// As above except this time the payment is due at the beginning of the month. This will reduce
// the payment slightly.
let due_at_beginning = true;
let pmt = payment(rate, periods, present_value, future_value, due_at_beginning);
dbg!(pmt);

// The payment is $210.7145, shown as negative since the present value was positive. It's
// slightly smaller (that is, closer to zero) than the payment in the case above where the
// payment was due at the end of the month.
assert_rounded_4(pmt, -210.7145);