HomeGuidesAPI Reference

Debt Relief

Help borrowers navigate the Biden-Harris Administration's Student Debt Relief Plan with Nexus.debtRelief

When a Borrower is trying to navigate the process of getting student loan forgiveness through the Biden-Harris Administration's Student Debt Relief Plan, Nexus.debtRelief is here to help.

🚧

In Active Development and things are changing

Please note the following information may be subject to change as the Biden administration rolls out the details and infrastructure of the One-Time Debt Relief program.

We are working closely with the Student Loan Servicing Alliance as well as monitoring information from the Department of Education to quickly respond to new information and update our tools and documentation accordingly.

Please don't hesitate to contact us if you have questions!

Understand how callbacks are triggered

Nexus triggers your callback function(s) with available results along some specific rules that apply to all workflows.

📘

The most important thing to keep in mind is that Nexus onExit and onSuccess callbacks are fired based on how the borrower exits Nexusnot based on the outcome of the workflow.

If the borrower chooses to exit Nexus via the X or cancel buttons—Nexus fires your onExit callback function.

If the borrower exits Nexus by making it to the final screen of the workflow—Nexus fires your onSuccess callback function.

Just to repeatonExit and onSuccess trigger based on how the borrower exits Nexus, not based on the outcome received from Nexus. If you want to know whether the borrower has more to do, you will want to look at the status attribute in the results sent to your callback function.

Calling Nexus.debtRelief

Nexus.debtRelief expects to receive a single options object as a parameter. This options object allows you to specify two possible callback functions:

  • onSuccess — a function to execute when your borrower exits the widget on the final screen
  • onExit — a function to execute when your borrower exits the widget early (by quitting/cancelling) or an error occurs
// Assuming you have a button your Borrower can click to start the debt relief flow
let debtReliefButton = document.querySelector('#nexus-debt-relief-button')

// Attach click handler to invoke Nexus.debtRelief
debtReliefButton.addEventListener('click', e => {
  Nexus.debtRelief({
    // the function to call when borrower exits on the final screen
    onSuccess: debtReliefHandler,
    // the function to call when borrower quits early (or error occurs)
    // for Nexus.debtRelief, we recommend using ONE callback function
    onExit: debtReliefHandler
  })
})

👍

We recommend using one callback function for Debt Relief

For Nexus.debtRelief, we strongly advise using the same callback function for both onExit and onSuccess. The Debt Relief program is still in flux, and it's possible to determine eligibility without visiting all the screens inside the Nexus.debtRelief workflow.

Why use one callback function?

We will return the debt_relief eligibility data in both onSuccess and onExit callback results (when available) because a borrower can go as far as determining they are eligible, and then they could quit the widget because that's all they wanted to know, or they aren't ready or don't have the time to complete all the data capture steps.

We don't want you to miss out on the eligibility results just because your borrower bails out early, so we ensure we send those results no matter how the borrower exits.

When are debt_relief results available?

Nexus will send the debt_relief results as long as they are available—even if eligibility has not yet been determined.

The only scenario in which the Nexus callback result will not have a debt_relief object is if the borrower never makes it past linking their servicers. This could mean they open the widget and do not proceed past the welcome screen, they hit the list of servicers and bail, they don't successfully link a servicer, or otherwise.

When is the workflow status complete?

Please note: Please do not confuse knowing eligibility with the status of the workflow being complete!

Nexus.debtRelief does more than just determine eligibility —and if someone is eligible, there is more to do until the form is completely submitted. When we have form submission in place (which is coming in the immediate future), that is the point where we will be able to return a result with both eligibility: "eligible" and status: "complete" if the borrower submits the form.

The status attribute in our callback result will only be complete right now if someone goes as far as determining their eligibility is either ineligible or unknown. That is a definitive point of certainty (or definitive uncertainty in the case of unknown eligibility).

If someone is eligible, the status attribute will not be complete until they submit the form. That is how we communicate to you that your borrower will need to come back because there is still work to be done—and since the form was only just released, we are still working on that part.

onSuccess callback

When your Borrower exits Nexus.debtRelief on the final screen, Nexus will execute the unary callback function you provide to the onSuccess option when invoking Nexus.debtRelief.

onExit callback

When your Borrower exits the Nexus.debtRelief workflow prematurely—which occurs when they cancel or otherwise quit Nexus, or when an error occurs starting a Nexus session—Nexus will execute the unary callback function you provide to the onExit option when invoking Nexus.debtRelief.

// We strongly recommend using ONE callback function
function debtReliefHandler(response) {
  // We recommend storing `response.status` so you can keep
  // track of which borrowers need to be prompted to return to
  // Nexus to complete their Debt Relief application.
  switch (response.status) {
    case "complete":
      // At this time, borrower is either ineligible OR
      // eligibility could not be determined.
      //
      // Borrowers can still be prompted to go back into the workflow
      // if you want to encourage them to verify their information
      // is correct—especially if they believe they are eligible.
      //
      // Inspect `response.result.debt_relief` for eligibility info.
      break;
    case "incomplete":
      // Borrower either quit the widget early OR they are eligible,
      // but have not completed submitting their Debt Relief application.
      //
      // Inspect the `response.result.debt_relief` object to identify
      // if they are eligible, if eligibility has not been determined
      // yet, and more info about their Debt Relief application.
      break;
    case "error":
      // You supplied an invalid Nexus key and/or Borrower UUID,
      // called an invalid workflow, or some other error occurred.
      break;
  }
}

Nexus.debtRelief response

Your callback function should expect a single object with additional information you can inspect and act on.

The Nexus.debtRelief response will contain three base properties, with the most important one being the result property, which itself will contain other critical information:

  • message—a string value indicating the workflow succeeded
  • result —an object that provides additional details and may change over time.
    • borrower—an object that provides additional details on the borrower for whom the Nexus workflow was performed.
      • uuid—the unique Payitoff UUID that identifies this borrower for API and Nexus calls
    • debt_relief—an object containing data about the Borrower's eligibility.
      • eligibility—a string value. May be "yes" if eligible, "no" if not, "not_determined" if we do not have enough information from the Borrower to determine eligibility, or "unknown" if we have the necessary information but still cannot determine eligibility.
      • eligibility_amount—an integer value indicating the maximum potential forgiveness for which the Borrower is eligible: 0 if ineligible or eligibility cannot be determined.
      • has_eligible_income: a string value indicating if the Borrower's income is below the eligibility threshold.
      • has_eligible_loans: a string value indicating if the Borrower has federal student loans potentially eligible for forgiveness
      • has_federal_loans: a string value indicating if the Borrower has federal student loans at all
      • has_loans_in_default: a string indicating if the Borrower has reported loans in default, which could make them eligible for forgiveness.
      • has_loans_paid_off: a string indicating if the Borrower has reported paying off student loans since March 13, 2020, which could make them eligible for reimbursement through the one-time forgiveness program.
      • has_no_loans: a string value indicating if the Borrower had no loans available
      • has_only_private_loans: a string value indicating if the Borrower linked only private student loans, which are not eligible for Debt Relief
      • has_pell_grant: a string indicating if the Borrower has received Pell Grants which doubles the maximum amount eligible for forgiveness from $10,000 to $20,000.
      • has_unidentified_ffel_loans: a string value indicating if the Borrower linked FFEL loans which could not be reliably determined as federal, which leads to eligibility being unknown
    • recommended_workflows—an array of strings for additional Nexus workflows you may want to initiate. For example, ["refi"] if a borrower has loans not eligible for forgiveness that could benefit from refinancing.
    • workflow—a string identifier of the workflow that was just completed
  • status—a string value, either "complete" if the Borrower is ineligible or "incomplete" if the Borrower is eligible but cannot yet apply and will need to return after the application is made available.

Example Scenarios and responses

Example callback response — Borrower is not eligible

In the example below, the onSuccess callback was fired after the borrower went as far as they could in the workflow. You can identify a few things:

  • The borrower is not eligible
  • Additional eligibility context information that explains why they are not eligible
  • The status is complete—because they are ineligible
{
  "message": "Debt relief complete",
  "result": {
    "borrower": {
      "uuid": "7c8c615c-1f3c-4d9c-8ee4-606e2248cd2b"
    },
    "debt_relief": {
      "eligibility": "no",
      "eligibility_amount": 0,
      "has_eligible_income": "no",
      "has_eligible_loans": "yes",
      "has_federal_loans": "yes",
      "has_loans_in_default": "no",
      "has_loans_paid_off": "no",
      "has_no_loans": "no",
      "has_only_private_loans": "no",
      "has_pell_grant": "no",
      "has_unidentified_ffel_loans": "no"
    },
    "recommended_workflows": [],
    "workflow": "debt_relief"
  },
  "status": "complete"
}

Example callback response — Eligibility not determined yet

In the example below, a borrower quits the widget in the middle of the workflow, before we've been able to determine their eligibility. You can identify a few things:

  • Eligibility has not been determined
  • Additional eligibility context information that explains why eligibility has not been determined yet
{
  "message": "Debt relief incomplete",
  "result": {
    "borrower": {
      "uuid": "a7aa379b-ca6f-4dd8-b14c-ee995db07927"
    },
    "debt_relief": {
      "eligibility": "not_determined",
      "eligibility_amount": 0,
      "has_eligible_income": "not_determined",
      "has_eligible_loans": "not_determined",
      "has_federal_loans": "yes",
      "has_loans_in_default": "not_determined",
      "has_loans_paid_off": "not_determined",
      "has_no_loans": "no",
      "has_only_private_loans": "no",
      "has_pell_grant": "not_determined",
      "has_unidentified_ffel_loans": "no"
    },
    "recommended_workflows": [],
    "workflow": "debt_relief"
  },
  "status": "incomplete"
}

Example callback response — Borrower is eligible, but form is not submitted

In the example below, a borrower quits the widget in the middle of the workflow, but after we've been able to determine they are eligible for Debt Relief. You can identify a few things:

  • The borrower is eligible for $10,000 in Debt Relief forgiveness
  • Additional eligibility context information that explains why they are eligible
  • The borrower has not submitted their application, so "status": "incomplete" is returned—you will want to reach out to the borrower in the future (when form submission is live) to have them complete final steps

NOTE: This response would be identical if the borrower had not quit early, and we instead triggered the onSuccess callback function.

{
  "message": "Debt relief incomplete",
  "result": {
    "borrower": {
      "uuid": "d7bc2935-faac-4b73-b062-b81157447ab7"
    },
    "debt_relief": {
      "eligibility": "yes",
      "eligibility_amount": 10000,
      "has_eligible_income": "yes",
      "has_eligible_loans": "yes",
      "has_federal_loans": "yes",
      "has_loans_in_default": "yes",
      "has_loans_paid_off": "yes",
      "has_no_loans": "no",
      "has_only_private_loans": "no",
      "has_pell_grant": "no",
      "has_unidentified_ffel_loans": "no"
    },
    "recommended_workflows": [],
    "workflow": "debt_relief"
  },
  "status": "incomplete"
}

📘

Borrower IDs

When relying on Nexus to create borrowers, you will need to store the borrower.uuid that is returned in order to make API calls on behalf of your borrowers.

📘

Nexus pre-fills information Payitoff knows about your borrowers

In order to ease the process for borrowers, Nexus will pre-fill all possible information required throughout the workflow. If a borrower has used Nexus before or you have already stored information for the borrower via our API, Nexus will populate any previously saved information such as name and contact info. The relevant Nexus screens will still be presented to the user so they may confirm or correct the pre-filled data as they complete the Debt Relief workflow.

👍

Track where your borrower left off with the status attribute

Payitoff highly recommend you capture the incomplete status and store it internally. This will prove to be a helpful engagement point in order to re-engage with users as well as prompt them to complete the workflow where they left off.