mono-logo

Credit Worthiness Guide

Last updated Aug 7th, 2024

Overview

The Credit worthiness resource provides summary information about the affordability status against a loan amount requested by your user. The Credit worthiness API takes key criteria such as Debt to Income ratio from transactions, specific loan details (principal, tenor, interest rate), and existing credit history into account, to assess a borrower's ability to repay a loan. This endpoint plays a crucial role in assessing the repayment capacity of potential borrowers who have linked their accounts to your business using Mono.

With this endpoint, you can assess a user’s financial profile and their potential to afford a specific loan amount using certain data points, minimizing the risk of default and ensuring responsible lending practices.

Integration Steps

To retrieve credit worthiness data on a linked financial account, you will need to pass specific loan application information from the borrower such as a custom principal amount, loan interest rate, and tenor.

Kindly note that there are two steps to getting Credit worthiness data on this API, these are:

  1. Initiate Credit-Worthiness Request: Starts the process of analysing existing transactions in a connected bank account and credit history data from the credit bureau, in the backgorund to generate credit worthiness report.
  2. Retrieve Credit-Worthiness Report: Retrieves the generated income records linked to a particular account via webhook.
1

Initiate Credit-Worthiness Request

This endpoint initiates the process of analysing all transactions in a connected bank account in the backgorund to generate credit worthiness report.

To utilize this endpoint, a POST request needs to be sent, containing the specific account ID of your user from Mono Connect as the path parameter. Upon receipt, an API response will be sent indicating that the creditworthiness process has begun which can then be accessed via webhook.

Request

1
POST https://api.withmono.com/v2/accounts/:id/creditworthiness

Request Path Parameter

  • id (required): This field expects the id of a connected bank account linked from mono connect sdk or account linking url.

Request Body Parameters

  • bvn required: This field expects the user's bank verification number (BVN)

  • principal required: This field expects the principal amount being given to the user (in Kobo)

  • interest_rate required: This field expects the interest rate e.g. 5

  • term  required: This field expects the term/number of months e.g. 12

  • run_credit_check required: This field expects a true/false value. When true, the user's credit history (i.e. the outstanding debt records) from the credit bureau, will be factored into the API decision engine. If false, the user’s credit history will not be factored in the computation.

  • existing_loans optional: This field allows you to pass your custom credit history records of existing loans accrued to a user from your end.

  • existing_loans.tenor: This number field expects the total number of months for a particular loan schedule.

  • existing_loans.date_opened: This date field expects the date a loan schedule was opened.

  • existing_loans.closed_date: This date field expects the date a loan schedule is meant to end.

  • existing_loans.institution: This string field expects the name of the institution that offered a loan to a user

  • existing_loans.institution: This string field expects the currency tied to a loan amount.

  • existing_loans.repayment_amount: This number field expects the total repayment amount to be made by a user.

  • existing_loans.opening_balance: This number field expects the opening balance of that scheduled loan.

  • existing_loans.repayment_schedule: This array of object field expects each object to contain a date schedule and the corresponding payment status if it was failed or paid.

cURL Sample Request

Request

123456789101112131415161718192021222324252627282930
curl --request POST \
  --url https://api.withmono.com/v2/accounts/id/creditworthiness\
  --header 'mono-sec-key: live_sk_your_app_key' \
  --header 'accept: application/json'
  --data 
{
  "bvn": "12345678901",
  "principal": 30000000,
  "interest_rate": 5,
  "term": 12,
  "run_credit_check": true,
  "existing_loans": [ //optional
    {
       "tenor": 10,
       "date_opened": "2023-10-31",
       "closed_date": "2024-09-27",
       "institution": "PROVIDUS BANK PLC",
       "currency": "NGN",
       "repayment_amount": 65408100,
       "opening_balance": 1200000000,
       "repayment_schedule": [
         {
           "10-2023": "paid",
           "11-2023": "paid",
           "12-2023": "failed"
         }
      ]
    }   
  ]
}

Request Headers

Include the following header in your request for authentication:

  • mono-sec-key (required): Your Mono secret key.

Success Response

If the initiation request is successful, you will receive the following API response:

Request

123456
{
    "status": "successful",
    "message": "The creditworthiness of SAMUEL, OLAMIDE NOMO is currently being processed. Once completed, the data will be sent to your webhook.",
    "timestamp": "2024-03-15T15:14:28.679Z",
    "data": null
}

Please note that the Credit-worthiness endpoint takes a bit of time to run computations in the background. Once the analysis is done, the credit-worthines report is sent to you via a webhook.

How Affordability is Determined

Affordability is determined using the Debt Service Coverage Ratio (DSCR), which compares a borrower’s net disposable income to their total debt obligations.

  • DSCR Calculation:DSCR = Net Disposable Income / Total Debt Service

Where:

  • Net Disposable Income = Gross Income - Expenses
  • Total Debt Service = Existing debt payments + New debt payments

This ratio helps assess whether the borrower can manage their current and proposed debt payments.

Use Cases

  1. Lending and Buy Now Pay Later (BNPL): To personalize loans to borrowers’ needs and repayment capacity, and minimize overall lending risk. This applies to all kinds of financing, micro loans, peer-to-peer loans, and more.

  2. Mortgage Approval: To assess a borrower’s ability to manage mortgage payments in conjunction with existing debt, ensuring they can handle both current and future financial obligations.

  3. Credit Card Issuance: To determine appropriate credit limits for new or existing credit cardholders based on their financial capacity and existing debt, reducing the risk of default.

  4. Rental Agreements: To evaluate potential tenants’ ability to meet rental payments by reviewing their disposable income and existing financial commitments, minimizing the risk of missed payments.

Did this page help you?