Student Loan Payoff Quote

Welcome developers! This guide will walk you through the implementation of our feature that allows you to fetch student loan payoff amounts and their valid-through dates. This enhancement introduces new capabilities and endpoints to our API, enabling richer insights into a user's student loan liabilities.

Implementation Summary

1️⃣ Fetch User Data:

Use the response from Ordering a credit report, or GET /v1/users?userId= endpoint to retrieve the user's student loan information, specifically looking at the capabilities array within each studentLoans object.

2️⃣ Check the Capabilities Matrix:

Verify if "LIABILITY_GROUP_PAYOFF_QUOTE" is "SUPPORTED" for the relevant liabilityGroupId.

3️⃣ Initiate Payoff Quote Fetch:

If the payoff quote data in the Get User response is not recent, or if you need to explicitly trigger a refresh, use the POST /v1/users/:userId/liabilities/refresh endpoint, providing the extRequestId and the relevant studentLoan objects with the appropriate capabilities and IDs.

4️⃣ Handle Webhooks (Recommended):

Subscribe to the LIABILITY_GROUP_PAYOFF_QUOTE_STATUS_CHANGE webhook events to receive real-time updates on the status of your payoff quote requests.

Key First Step: The Capabilities Matrix

Before you can request a student loan payoff quote, it's crucial to understand and utilize the capabilities matrix. This matrix, accessed via the capabilities array, signals the availability of specific actions or data points for a given liability.

You may check the capabilities within the GET /v1/users?userId= endpoint response to confirm that LIABILITY_GROUP_PAYOFF_QUOTE is listed as SUPPORTED for the relevant studentLoanId or liabilityGroupId. Attempting to fetch a payoff quote without confirming the capability will result in an error.

"capabilities": {  
  "payments": { ... },  
  "data": {  
    "liabilityGroupPayoffQuote": {  
      "availability": "SUPPORTED",  //"SUPPORTED": Indicates that a consolidated payoff quote can be fetched for the student loans within the specified liabilityGroupId.
      "liabilityGroupId": "<liabilityGroupId>"  
    }  
  }  
}

📘
Note on Liability Groups: A liabilityGroupId is a logical grouping of individual liabilities (in this case, student loans) under a single institution. It allows for actions and data retrieval at a group level. You can identify the liabilityGroupId associated with a set of student loans within the capabilities.data.liabilityGroupPayoffQuote section of the Get User response. This is distinct from the institution ID.

New and Updated Endpoints

Here's a breakdown of the new and updated endpoints related to fetching student loan payoff quotes:

Trigger Student Loans Payoff Fetch

Endpoint: POST /v1/users/:userId/liabilities/refresh

This endpoint allows you to initiate the process of fetching the latest payoff quotes for specific student loans or liability groups.

Request Body:

{  
  "extRequestId": "<UUID>", //A unique identifier for this refresh request, allowing you to track its progress. 
  "studentLoans": [  //An array specifying the student loans or liability groups for which to fetch payoff quotes.
    {  
      "capabilities": [  
        "LIABILITY_GROUP_PAYOFF_QUOTE"  
      ],  
      "liabilityGroupId": "<liabilityGroupId>"  //The specific liabilityGroupId for which to fetch a consolidated payoff quote. Required when requesting "LIABILITY_GROUP_PAYOFF_QUOTE".
    }  
  ]  
}

Response Body (Success - HTTP 200):

{  
  "status": {  
    "code": 200,  
    "desc": "success"  
  },  
  "data": [  
    {  
      "refreshTransactionStatus": "IN_PROGRESS",  
      "refreshTransactionId": "<UUID>",  
      "userId": <userId>,  
      "liabilityGroupId": "<liabilityGroupId>",  
      "studentLoanIds": ["<studentLoanId1>", "<studentLoanId2>"],  
      "nextEligibleRefreshOn": 1678725487099,  
      "liabilityType": "STUDENT_LOAN",  
      "capability": "LIABILITY_GROUP_PAYOFF_QUOTE"  
    }  
  ]  
}

LIABILITY_GROUP_PAYOFF_QUOTE_STATUS_CHANGE Webhook Event

This event is triggered when the status of a payoff quote request for a liability group changes.

Webhook Payload:

{  
  "webhookId": "",  
  "eventType": "LIABILITY_GROUP_PAYOFF_QUOTE_STATUS_CHANGE",  
  "liabilityType": "STUDENT_LOAN",  
  "userId": "string",  
  "extRequestId": "string",  
  "refreshTransactionId": "string",  
  "liabilityGroupId": "string",  
  "refreshTransactionStatus": "COMPLETED | FAILED",  
  "nextEligibleRefreshOn": 1678724489099,  
  "studentLoanIds": ["<studentLoanId>"],  
  "data": {  
    "payoffAmount": number,  
    "payoffGoodThroughDate": "YYYY-MM-DD",  
    "updatedOn": 1678724487095  
  }  
}

Get User (Updated Response)

Endpoint: GET /v1/users?userId=

The response for this endpoint has been updated to include payoff quote information directly at both the individual loan and liability group levels. This allows you to retrieve the latest payoff quotes without making a separate refresh call, provided the data is current.

Updated Response Body Snippet:

{  
  "status": { ... },  
  "data": {  
    "userId": "UUID",  
    "extUserId": "UUID",  
    "profile": { ... },  
    "creditReports": [ ... ],  
    "studentLoanSummary": {  
      "noOfLoans": Number,  
      "currentOutstandingBalance": Number,  
      "minimumPaymentAmount": Number,  
      "updatedOn": EpochTs,  
      "liabilityGroupPayoffQuotes": [{  //An array containing the latest payoff quotes for liability groups associated with the user.
        "studentLoanIds": ["<studentLoanId>"],  
        "liabilityGroupId": "liabilityGroupId",  
        "payoffAmount": 28041,  
        "payoffGoodThroughDate": "YYYY-MM-DD",  
        "updatedOn": 1678724487099  
      }]  
    },  
    "studentLoans": [  
      {  
        "studentLoanId": "<studentLoanId>",  
        "liabilityProfile": { ... },  
        "statementSummary": { ... },  
        "balanceDetails": { ... },  
        "creditor": { ... },  
        "capabilities": { ... },  
        "updatedOn": 1678724487099,  
        "createdOn": 1678724487099  
      }  
    ]  
  }  
}

Alternative to Webhooks (Not preferred)

Poll Student Loans Payoff Fetch Status

Endpoint: GET /v1/users/:userId/liabilities/refresh/:extRequestId

Use this endpoint to poll the status of a previously initiated payoff quote fetch request using the extRequestId.

Response Body (Success - HTTP 200):

{  
  "status": {  
    "code": 200,  
    "desc": "success"  
  },  
  "data": [  
    {  
      "refreshTransactionStatus": "COMPLETED",// Indicates the final status of the refresh process (COMPLETED or FAILED).  
      "refreshTransactionId": "<UUID>",  
      "userId": <userId>,  
      "liabilityGroupId": "<liabilityGroupId>",  
      "studentLoanIds": ["<studentLoanId1>", "<studentLoanId2>"],  
      "nextEligibleRefreshOn": 1678724487099,  
      "liabilityType": "STUDENT_LOAN",  
      "capability": "LIABILITY_GROUP_PAYOFF_QUOTE",  
      "payoffAmount": 55000, //The total payoff amount for the student loan or liability group.
      "payoffGoodThroughDate": "YYYY-MM-DD",//The date until which the payoffAmount is valid (YYYY-MM-DD format).
      "updatedOn": 1678724487099  //A Unix timestamp indicating when the payoff quote was last updated.
    }  
  ]  
}

By following these steps, you can seamlessly integrate the new student loan payoff quote functionality into your application, providing valuable insights to your users. Please don't hesitate to reach out to your Spinwheel representative if you have any questions or require further clarification.