HomeGuidesAPI Reference

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 periodscheduled_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

PropertyTypeFormatDescription
action_itemsarrayDeprecated. Will be removed in API v2.
amount_forgivennumberfloatTotal amount of outstanding Loan balance that will be forgiven at the end of the current Repayment Plan's term.
annual_snapshotsarrayTODOTODO
eligible_loansarrayLoanAn array of Loan objects which meet the eligibility criteria for this RepaymentOption.
estimated_tax_liabilitynumberfloatEstimated tax bomb, or the amount a Borrower will have assessed as income based on total amount forgiven by their Repayment Plan.
final_monthly_paymentnumberfloatThe amount of the final monthly payment.
ineligible_loansarrayLoanAn array of Loan objects which do not meet the eligibility criteria for this RepaymentOption.
ineligible_reasonsarraystringAn array of reasons Loans or a Borrower may not meet eligibility criteria for this RepaymentOption.
namestringThe name of the Repayment Plan this RepaymentOption represents.
number_of_paymentsintegerint32Total number of payments that will be made over the course of the repayment term.
pslf_eligiblebooleanIs this RepaymentOption eligible for PSLF forgiveness?

Defaults to false.
repayment_planobjectRepaymentPlanA RepaymentPlan object with full details on the Repayment Plan this RepaymentOption represents.
scheduled_monthly_paymentnumberfloatThe regular monthly payment a borrower would pay under normal conditions, but is unlikely to pay during COVID forbearance.
starting_monthly_paymentnumberfloatThe monthly payment a borrower is expected to pay during COVID forbearance (which should always be 0.00).
total_costnumberfloatThe 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_paidnumberfloatThe 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
}