HomeGuidesAPI ReferenceChangelog

RepaymentOption

Payitoff API: RepaymentOption Schema

A RepaymentOption object returns all the financial details of a given Repayment Plan, properly calculated for your Borrower and their unique situation, allowing you to provide a unique Assessment tailored just for their needs—enabling them to compare various Repayment Plans against their current Repayment Plan, and choose a Plan that works best for their goals and needs.

📘

Understand total_paid vs total_cost

total_paid is the sum of all monthly payments a borrower will make on a loan's current Repayment Plan over its lifetime.

With Income-Driven Repayment plans, there is sometimes a "tax bomb" at the end of their repayment term—any outstanding balance is forgiven, but treated as taxable income. Thus, total_cost provides the sum of total_paid plus the taxes owed on that forgiven amount (which is calculated and provided in the amount_forgiven and estimated_tax_liability properties). In other words,total_cost is the bottom line amount a borrower will pay to dispense of their loan on a RepaymentOption.

📘

Understand scheduled_monthly_payment vs starting_monthly_payment

When you look at RepaymentOption objects, you will notice there are two monthly payment properties—scheduled_monthly_payment and starting_monthly_payment. Though confusing, these values are provided separately to help a borrower make the best financial decisions for their futures, not just during this historically anomalous time.

During the ongoing COVID forbearance period—currently scheduled to end 2021-09-30—scheduled_monthly_payment provides the monthly payment a borrower would pay under normal conditions.

On the other hand, starting_monthly_payment provides the monthly payment a borrower is expected to pay during COVID forbearance (which should always be 0.00).

When the COVID forbearance period ends, both scheduled_monthly_payment and starting_monthly_payment should hold identical values.

Schema Definition

Property

Type

Format

Description

action_items

array

Deprecated. Will be removed in API v2.

amount_forgiven

number

float

Total amount of outstanding Loan balance that will be forgiven at the end of the current Repayment Plan's term.

annual_snapshots

array

TODO

TODO

eligible_loans

array

Loan

An array of Loan objects which meet the eligibility criteria for this RepaymentOption.

estimated_tax_liability

number

float

Estimated tax bomb, or the amount a Borrower will have assessed as income based on total amount forgiven by their Repayment Plan.

final_monthly_payment

number

float

The amount of the final monthly payment.

ineligible_loans

array

Loan

An array of Loan objects which do not meet the eligibility criteria for this RepaymentOption.

ineligible_reasons

array

string

An array of reasons Loans or a Borrower may not meet eligibility criteria for this RepaymentOption.

name

string

The name of the Repayment Plan this RepaymentOption represents.

number_of_payments

integer

int32

Total number of payments that will be made over the course of the repayment term.

pslf_eligible

boolean

Is this RepaymentOption eligible for PSLF forgiveness?

Defaults to false.

repayment_plan

object

RepaymentPlan

A RepaymentPlan object with full details on the Repayment Plan this RepaymentOption represents.

scheduled_monthly_payment

number

float

The regular monthly payment a borrower would pay under normal conditions, but is unlikely to pay during COVID forbearance.

starting_monthly_payment

number

float

The monthly payment a borrower is expected to pay during COVID forbearance (which should always be 0.00).

total_cost

number

float

The sum of total_paid plus estimated_tax_liability owed on total amount_forgiven. In other words, total_cost is the bottom line amount a borrower will pay to dispense of their loan on the current Repayment Plan.

total_paid

number

float

The sum of all monthly payments a Borrower will make on a loan's current Repayment Plan over its lifetime.

Example

{
  "action_items": [],
  "amount_forgiven": 0,
  "annual_snapshots": [],
  "eligible_loans": [],
  "estimated_tax_liability": 0,
  "final_monthly_payment": 0,
  "ineligible_loans": [],
  "ineligible_reasons": [
    "No partial financial hardship",
    "New Borrower Date is required",
    "Qualifying PAYE requires Adjusted Gross Income",
    "Qualifying PAYE requires Residence",
    "Qualifying PAYE requires Family Size",
    "No eligible loans"
  ],
  "name": "Income-Based (2009)",
  "number_of_payments": 0,
  "pslf_eligible": true,
  "repayment_plan": {
    "description": "Income Based Repayment Plan (2009)",
    "idr": true,
    "name": "IBR",
    "type": "ibr"
  },
  "scheduled_monthly_payment": 0,
  "starting_monthly_payment": 0,
  "total_cost": 0,
  "total_paid": 0
}

Did this page help you?