HomeGuidesAPI Reference


The most common scenario you'll encounter while trying to help borrowers take control of their student loans looks like this:

  • A single <<glossary:Borrower>>

  • tens of thousands of dollars (or more!) in student loan debt

  • currently on a Standard or Graduated <<glossary:Repayment Plan>>

  • current payment is a significant chunk of their monthly income

  • wants to switch to an <<glossary:Income-Driven Repayment Plan>>

# Add Nexus to Your App

Start integrating Payitoff in your product(s) by adding <<glossary:Nexus>> to your app or page.

### Adding the Nexus `script` tag

You must include the <<glossary:Nexus>> `script` tag in your app's markup. Where you place it in your markup is up to you, of course, but you must ensure it is included and loaded _before_ any event handlers are triggered by your `Borrowers` as they interact with your product(s).



Integration begins in the Payitoff Sandbox

For local development, staging, and testing environments, you'll want to include the **sandbox** version of Nexus.

Payitoff's Sandbox is your development playground—it will never connect to live <<glossary:Servicer>> websites, it won't submit real <<glossary:Enrollment Requests>>, it always returns dummy data where necessary, and you'll use a Sandbox <<glossary:Nexus Key>> that only works in our Sandbox environment.

Don't have your Nexus key or API key?

Please contact [[email protected]](🔗) and we'll get that sorted.

# Create Your First Borrower

Every Nexus session is `Borrower`-specific, so we'll use the [Create Borrowers API endpoint](🔗) to make your first API call and create your first `Borrower`.



Borrowers have `id` and `uuid` values

Every `Borrower` created via API will have an `id` and `uuid`. You should save **both** values in your systems.

When calling API endpoints, `id` and `uuid` are largely interchangeable in v1.0.0, and you'll typically see examples in API v1 documentation using `id` values. However, new API endpoints, and Nexus itself, expect to receive a Payitoff UUID when you make calls with our identifiers.

# Initialize Nexus

With your first `Borrower` created, your <<glossary:Nexus Key>>, and the Nexus script tag in your page, you can now initialize Nexus in your app. Nexus works on behalf of your `Borrowers` to enable linking every <<glossary:Servicer>> they have relationships with, creating <<glossary:Enrollment Requests>>, and more in the future. You should plan your integration with Nexus accordingly—the instantiated Nexus object can only operate on a single `Borrower` at a time.



Use a Payitoff UUID or Your Own Borrower ID

If the `borrower` identifier you supply doesn't look like a valid `UUID` from our system, or no `Borrower` is found, we'll look up a `Borrower` using the `borrower` value as an _external_ identifier. We manage this internally, but any value you supply that doesn't match our own `UUID`s will result in either fetching **or creating** a `Borrower` with your `borrower` value as their external ID. Find out more details in our [Nexus initialization docs](🔗).

# Use Nexus to link servicer accounts

The first major step for learning more about your `Borrower` is to have them link all of their `Servicers`. Most `Borrowers` only have one `Servicer`, but there are still many `Borrowers` who have relationships with multiple `Servicers`—for example, a `Borrower` whose undergraduate loans are with one `Servicer`, but their graduate loans are handled by a different `Servicer`. Nexus makes it easy for your `Borrower` to choose all of the `Servicers` they pay monthly and connect their accounts so we can collect the most accurate information about their <<glossary:Loan Portfolio>>.

### A brief overview of Nexus workflows

Nexus currently offers three workflows— [`link`](🔗), [`assess`](🔗), and [`enroll`](🔗). Learn more about each workflow on the main [Nexus doc page](🔗).

Every Nexus workflow allows you to provide two callbacks—`onSuccess` and `onExit`. The `onExit` callback will be executed whenever your `Borrower` cancels the workflow or if a system error is encountered. The `onSuccess` callback will be executed whenever your `Borrower` successfully completes the workflow.

### Invoke `Nexus.link`

With Nexus initialized in your app, you'll want to invoke the `Nexus.link` workflow to trigger displaying Nexus to your users so they can link all of the `Servicers` with whom they have accounts.



Nexus in Sandbox never connects to real Servicers

Keep in mind that Nexus will never connect to real Servicer sites when in Sandbox. Nexus will be fully operational, provide different authentication experiences, and return dummy data to build out `Borrowers` and their loan portfolios.

### Simulate specific experiences when linking `Servicers`

It is possible to simulate different authentication experiences during development when using Nexus in Sandbox.

Default Nexus Sandbox experience is to login with no challenge

The default Nexus experience in Sandbox is to authenticate a `Borrower` _without_ a challenge question. This means **you can use any unreserved username and password and Nexus will accept it**. See more authentication scenarios in our [`Nexus.link`](🔗) doc.

# Update Borrower info with API

So, your `Borrower` has linked their `Servicer`(s), and it's time to move forward with providing an <<glossary:Assessment>> of their <<glossary:Repayment Options>> and preparing to create <<glossary:Enrollment Requests>>.

Earlier, [in Step 2](🔗), you created your first `Borrower` with only a `first_name` and `last_name`. When your `Borrower` links their `Servicer`(s) via Nexus, we collect more information about them and their <<glossary:Loan Portfolio>>, but you'll still need to provide a few key pieces of information about your `Borrower` to perform an Assessment:

  • `agi` — their <<glossary:Adjusted Gross Income>>

  • `filing_status` — their <<glossary:Tax Filing Status>>

  • `family_size` — the <<glossary:Family Size>> claimed on their taxes

  • `state_of_residence` — the state in which they reside

We must have at least these 4 pieces of information to determine eligibility and calculate Repayment Options, so let's update our Borrower with the [Update Borrower API endpoint](🔗).



# Fetch Repayment Options and Show Assessment

An <<glossary:Assessment>> is helpful to your `Borrowers` because it allows them to compare the financial impact of Income-Driven Repayment Plans for which they're eligible to their current repayment situation.

<<glossary:Repayment Options>> are the foundation of presenting an Assessment to your `Borrower`. With your `Borrower` successfully updated, you're ready to fetch available Repayment Options from the [Repayment Options API endpoint](🔗).



Repayment Options API provides all you need for an Assessment

Your `Borrower` will want to compare Income-Driven Repayment Plans to the financial impact of their current plan(s). The [Repayment Options API endpoint](🔗) makes this easy by returning an `original` object, which provides a summary of their current <<glossary:Repayment Plan>>, as well as a `repayment_options` array with the details of available options they may or may not be eligible for.

### A quick look at `original` Loan details

The [Repayment Options API endpoint](🔗) returns a high-level summary of the financial impact of your `Borrower`'s current Repayment Plan. When building your own Assessment experience, `original` provides all the relevant details you'll want to compare to each available Repayment Plan.



### A quick look at a Repayment Option

The [Repayment Options API endpoint](🔗) also returns a `repayment_options` array, providing details on available Repayment Plans, whether or not your `Borrower` is eligible for the plan, and more for you to show your `Borrower` how each plan impacts their current financial picture, as well as their future goals.



Your Borrowers won't be eligible for every Repayment Option

Available Repayment Options have their own eligibility rules, and you should expect your `Borrower` won't be eligible for every available Repayment Plan. When this is the case, you'll find that `ineligible_loans` **will not** be an empty array. You will also find details on why your `Borrower` is ineligible for a given Repayment Option in the `ineligible_reasons` array. If both `ineligible_loans` and `ineligible_reasons` are empty arrays, and `eligible_loans` is a non-empty array, you can trust that the Repayment Option is available for your `Borrower` to choose.

### Understand `total_paid` vs `total_cost`

When presenting eligible Repayment Options to your `Borrower`, you'll likely want to draw their attention to understanding and evaluating the difference between `total_paid` and `total_cost` across their available options.

#### `total_paid` reflects monthly payments only

The `total_paid` property provides the sum of all monthly payments a `Borrower` will make on each of their loan's over the life of a Repayment Plan.

#### `total_cost` is the true bottom line expense

With Income-Driven Repayment plans, there is sometimes a _tax bomb_ at the end of the repayment term—any outstanding balance that is forgiven will be treated and assessed to the `Borrower` as _taxable income_. This can be found in the Repayment Option details in the `amount_forgiven` property. If `amount_forgiven` is non-zero, you will want to ensure your `Borrower` understands there could be a tax bomb by presenting the amount provided in the `estimated_tax_liability` property. If `estimated_tax_liability` is non-zero, then the Repayment Option includes a forgiven amount that will be taxed as income. In this scenario, `total_cost` provides the sum of `total_paid` (all monthly payments over the repayment term) _plus_ the `estimated_tax_liability`.

In other words, `total_cost` is the bottom line amount your `Borrower` will pay out-of-pocket to dispense of their loan on a given Repayment Plan.

# Use Nexus to create an Enrollment Request

Having presented an Assessment to your `Borrower`, they will likely find a new Repayment Option that is better than their current plan. Your Assessment experience should allow your `Borrower` to select a better plan with a button, link, or some kind of UI control.

Once your `Borrower` has selected the Repayment Plan they would like to enroll in, it's time to let Nexus walk them through creating <<glossary:Enrollment Requests>> that will be submitted to their `Servicer`(s).



### A quick look at a `Nexus.enroll` response

When your `Borrower` successfully submits their Enrollment Request to change plans, Nexus will execute your `onSuccess` callback, providing it with a JSON response that provides submission details you can store and show your `Borrower`:



Key Enrollment response properties

Whenever you submit an Enrollment Request (via Nexus or our API), there are a few fields worth paying attention to.

We recommend you save the `Enrollment.id` value returned in the submission response. This will help you get more details and check its status with subsequent requests to our API.

Your `Borrower` likely wants to have some idea of when they can expect to know more about their submitted Enrollment Requests. We recommend showing your `Borrower` the `estimated_approval_date` from the submission response, as this can help set their expectations for how long the Enrollment and Repayment Plan-changing process can take.

To check the status of submitted Enrollment Requests after they are created, use our API and the `Enrollment.id`. You'll want to check the `status` object in the response, particularly the `status.description` and `status.type` property to update your own records and share the current status with your `Borrower`. The `status.updated_at` property tells you when the last status update occurred.

# Congratulations!

That's it! You've successfully integrated Payitoff into your tools for the most common use case. To recap, we have completed the following steps:

  • Added Nexus to your application

  • Created your first `Borrower`

  • Saved Payitoff's `Borrower.id` and `Borrower.uuid` values on your local `Borrower` record for later usage

  • Used Nexus to connect to one or more Servicers as a `Borrower`

  • Updated your `Borrower` with `agi`, `filing_status`, `family_size`, and `state_of_residence`

  • Retrieved Repayment Options

  • Presented them to your `Borrower`

  • Chose a Repayment Option

  • Used Nexus to create an Enrollment Request for the chosen Option

# Next Steps

With your first integration out of the way, check out our other guides to better understand Nexus, our API, advanced topics, best practices, and more.