👍

Check out our Integration Guides

While these pages document how to include, initialize, and use Nexus, we highly recommend checking out our Integration Guides to familiarize yourself with the Payitoff domain, and how you can use Nexus in 10 minutes, or use Nexus with our API to build custom experiences where it matters most to you, and leave the heavy lifting to us.

How to use Nexus

There are a number of ways you can use Nexus in your own products.

Nexus provides three distinct workflows you can use:

Link — Get accurate loan portfolio data and speed up Enrollments

Nexus.link is the function to call if all you want to do is enable borrowers to link their servicer accounts and build a Loan Portfolio.

Assess — Calculate, present, and compare Income-Driven Repayment Options

Nexus.assess is the function to call if you want to help borrowers view eligible Repayment Options, choose a Repayment Plan, and are not building your own Assessment UX on top of our Get Repayment Options API endpoint.

If we already have a borrower's Loan Portfolio built out, we'll skip linking—otherwise, you can call Nexus.assess with a new borrower and we will walk them through linking their servicer account(s) before calculating and presenting Repayment Plan comparisons.

Enroll — Submit an Enrollment Request for a new IDR plan

Nexus.enroll is the function to call when your end goal is to submit an Enrollment Request on behalf of a borrower who wants to switch to an Income-Driven Repayment Plan.

If you do not know what plan your borrower wants

You can call Nexus.enroll with callback functions only, and omit the plan parameter. This will instruct Nexus.enroll to walk a borrower through linking servicers if necessary, present Repayment Options, allow the borrower to choose a Repayment Plan, and culminates in walking the borrower through submitting Enrollment Requests.

If you already know what plan your borrower has chosen

In situations where you're providing your own Assessment UX on top of our API, or you remembered what plan a user chose when previously using Nexus.assess—you can call Nexus.enroll and provide the plan parameter. This will save the user some steps they've already completed, and will skip the Assess workflow entirely. Nexus will have the borrower link their servicer account(s) if they haven't already, and will then walk them through all the necessary steps to submit Enrollment Requests.

Regardless of whether the borrower completes or exits the workflow you've called, Nexus will dismiss itself automatically and trigger your onSuccess or onExit callback function(s), depending on whether the workflow is completed or exited prematurely.

📘

Which Nexus workflow should I call?

When thinking about which Nexus workflow to call, think about when you want the borrower to exit the Nexus widget.

Only want them to link their servicer accounts and then be brought back to your app? Use Nexus.link.

Do you want them to view an Assessment and choose a Repayment Plan, then be brought back to your app? Use Nexus.assess.

Do you want them to submit an Enrollment Request? Use Nexus.enroll.

Get Started

Include Nexus script tag

In local development, staging, and testing environments, you'll want to include the sandbox version of Nexus:

<script src="https://payitoff-cdn.io/sandbox/nexus/js/v1"></script>

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

Going to production?

When you're ready to go to production with your Nexus-powered integration, you'll need a production Nexus Key and you'll want to update your script tag's src property to use the production URL:

<script src="https://payitoff-cdn.io/nexus/js/v1"></script>

🚧

Don't have your Nexus Key?

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

Initialize Nexus

With your 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 Servicer they have relationships with, providing Assessments, creating Enrollment Requests, and more in the future.

Initializing Nexus is a simple JavaScript call away. Simply provide an options object with the following two properties:

• nexus_key—your company's individual Nexus Key
• borrower—the unique identifier of a Borrower you're invoking Nexus for

📘

The instantiated Nexus object can only operate on a single Borrower at a time.

Initialize Nexus with Payitoff UUID

If you already have a Payitoff UUID for your Borrower—for example, because you create Borrower records with our API and store the UUID values—you can supply it along with your Nexus key to initialize Nexus to walk your borrower through Nexus link, assess, and enroll workflows.

Nexus({
  nexus_key: 'GIVINGHERALLSHESGOT',
  borrower: '72edfd83-eca2-4383-a015-ff7a230504c2'
})

On load, Nexus will try to find a Borrower using the borrower identifier you supply—if it looks like a UUID from our API. So, if you supply a Payitoff UUID as your borrower value, we'll find the associated Borrower and verify it belongs to your account, then Nexus will be ready to use.

NOTE: If you supply a UUID that can't be found, we'll treat it as if you'd supplied an external unique identifier (see next section).

Initialize Nexus with your own unique borrower identifiers (and create new borrowers!)

In response to requests from our partners, we've recognized that it can be somewhat awkward to create a Borrower via our API before invoking Nexus. To solve this use-case, we've improved Nexus to allow you to provide your own unique identifiers in the borrower property when initializing Nexus.

Nexus({
  nexus_key: 'GIVINGHERALLSHESGOT',
  borrower: 'jamestkirk1966'
})

🚧

Using Nexus, but not using our API?

If you do not currently use the Payitoff API, but want to integrate Nexus into your product(s), this is the Nexus initialization option you want to be using.

NOTE: We still encourage you to save the borrower.uuid value that is returned in all Nexus callback responses, as Payitoff UUID values are the only supported way to interact with our API.

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 UUIDs will result in either fetching or creating a Borrower with your borrower value as their external ID.

To recap, you can provide your own unique borrower value from your system, and we will create, save, and lookup your Borrowers using that value in Nexus.

• If you are showing Nexus to users who have never used Nexus before, we will create Borrower records for you, tied to your partner account. We will return the Payitoff borrower.uuid in Nexus callback responses so you can save our UUID values to your user records for later use.
• All subsequent interactions and initialization of Nexus will always find that same Borrower record with the external ID you supplied as your borrower value.
• Whether the borrower value is a Payitoff UUID or your own value, it must be unique. If you provide the same borrower value when initializing Nexus for multiple users in your system, a Borrower record will only be created once—and every subsequent interaction from multiple users in your app will update the same Borrower record. Don't do that.