Borrower Onboarding and Loan Application

Aggregated API endpoint for borrower onboarding and loan application

Introduction

This api endpoint aggregates all the steps involved in borrower onboarding and loan application into a single api call. This api handles creating the borrower, verifying the borrower bank account details, and processing a default loan for the created borrower. To have a better understanding of the steps involved in onboarding a borrower, please check Borrower Onboarding

When the endpoint is called,

1. The system checks to see if the borrower with the provided identity number exists for the aggregator. If the borrower exists, the onboarding flow proceeds to the next step which is the bank account verification. If the borrower does not exist for that aggregator, the borrower is created under that aggregator.

2. Upon bank account verification; if the borrower has a bank account already registered, the onboarding flow proceeds to loan request and approval. However, if a bank account does not exist, the bank account is verified and added for that borrower.

3. Once bank account is done, loan request and approval is done. see Loan Request and Approval

See Borrower Onboarding and Loan Application endpoint below.

Get Country's States

GET {{BaseUrl}}api/v1/account/all_state?country_code=NG

Endpoint to get list of states for a specific aggregator's country. Call this endpoint to get the respective states based on an aggregator's country before processing borrower onboarding and loan application

Query Parameters

Name	Type	Description
aggregator_id	string	The specific aggregator whose nationality you want to get states for
state_id	number	The id of the single state you want to retrieve for a nationality
country_code	string	The country code of the aggregator's nationality

200

{
  "data": [
    {
      "id": 1,
      "name": "Abuja",
      "state_code": "FC",
      "country_code": "NG"
    }
  ],
  "message": "Success",
  "status": true,
  "status_code": 200
}

Get Country's Bank List

GET {{BaseUrl}}api/v1/account/signed_banks_country?country_code=NG

Endpoint to get all bank list for a specific aggregator's country. Call this endpoint to get respective banks before processing borrower onboarding and loan application.

Query Parameters

Name	Type	Description
country_code	string	The aggregator's country code eg: NG, KE

200

{
    "data": [
        {
            "id": number,
            "name": " string",
            "slug": "string",
            "code": "string",
            "longcode": "string",
            "vigipay_bank_id": "string",
            "country_code": "string"
        },
    "message": "Success",
    "status": true,
    "status_code": 200
}

Get Sectors

GET {{BaseUrl}}/api/v1/misc/sectors

Endpoint to get all sectors.

200

{
  "data": [
    {
      "category_id": 1,
      "category_name": "agriculture",
      "category_slug": "agriculture",
      "code": "CF23660"
    }
  ],
  "message": "Success",
  "status": true,
  "status_code": 200
}

Get Aggregator Products

GET {{BaseUrl}}/api/v1/misc/query_product_by_aggregator

Headers

Name	Type	Description
Authorization	string	The bearer token of the authenticated aggregator

200

{
    "data": [
      {
        "id": 1,
        "product_code": "ABC",
        "product_name": "New Product",
        "maximum_amount": 1000000,
        "pub_date": "01/01/2021 00:00:00",
        "modified_date": "01/01/2021 00:00:00",
        "productCategoryName": "TEST Category",
        "interest_rate": 10,
        "maximum_tenor": 12,
        "aggregator_id": 1,
        "product_category_id": 13,
        ...
      },
      "message": "Products queried successfully",
      "status": true,
      "status_code": 200
  ]
}

Borrower Onboarding and Loan Application

POST {{BaseUrl}}/api/v1/account/loan_application

Endpoint to process borrower onboarding and loan application.

Headers

Name	Type	Description
Authorization	string	Authorised token received after successful aggregator authentication

Request Body

Name	Type	Description
last_name	string	The last name of the borrower
first_name	string	The first name of the borrower
bank_account_name	string	The name of the borrower's bank account. This is required only for non Nigerian aggregators.
identity_number	string	This is the unique valid identification number of the borrower used to perform KYC.
email	string	The borrower's email.
phone_number	string	The borrower's phone number.
gender	string	The gender of the borrower which should either be male or female
photo_url	string	The base 64 image of the borrower or the url of the uploaded image.
residence_address	string	Address of the borrower.
city	string	City of the borrower.
state	string	State of the borrower. To view list of states under an aggregator see Get Country's States endpoint above.
date_of_birth	string	Borrower's date of birth in the format yyyy-MM-dd
borrower_type	integer	The type of borrower to be onboarded. 1 for individual and 2 for corporate.
company_name	string	The name of the company being registered for corporate borrower.
registration_number	string	Company's business registration number for corporate borrower.
company_address	string	Company address for corporate borrower.
company_city	string	City where company is located for corporate borrower.
company_state	string	State where company is located for corporate borrower. To view all states for an aggregator nationality, see Get Country's State endpoint above.
bank_account_num	string	The bank account number of the borrower.
bank_code	string	The bank code of the borrower's bank. To view all banks and their bank codes see Get Country's Bank List endpoint above.
aggregator_loan_ref	string	The unique loan reference for the aggregator. This will be generated by the client.
product_id	integer	The Id of the product from which the loan is being requested. To view all the products for a particular aggregator see Get Aggregator Product endpoint above
sector_code	string	The sector code of the borrower applying for the loan. To view all sectors and their sector codes, see the Get Sectors endpoint above.
loan_tenure	integer	The duration of the loan in months
loan_amount	number	The amount to be loaned-out.
annual_interest_rate	number	The loan interest rate. If the interest rate is zero, the loan product's interest rate will be used.
loan_purpose	string	The reason for which the the loan is created.
customer_category	string	The customer's job category
create_wallet	boolean	This indicates if wallet is to be created for a user or not (true or false)
country_code	string	Certified country code is entered here such as "NG" (Nigeria), "GH" (Ghana), "SA" (South Africa)

200

{
    "loan_reference": "ABC123",
    "message": "Your bank account will be credited within 24hours if your application is approved.",
    "status": true,
    "status_code": 201
}

400

{
    "message": "Error message here",
    "status": false,
    "status_code": 400
}

401

{
    "message": "Unauthorized",
    "status": false,
    "status_code": 401
}

404

{
    "message": "Error message here",
    "status": false,
    "status_code": 404
}

500

{
    "message": "Server error",
    "status": false,
    "status_code": 500
}

Get Loan by Reference

GET {{BaseUrl}}/api/v1/eco/agg_search_loans

Endpoint to fetch a loan by using either aggregator generated loan reference or Advancly generated loan reference. The loan status can be found in the status field of the response

Query Parameters

Name	Type	Description
aggregator_loan_ref	string	Aggregator generated reference
loan_ref	string	Advancly generated reference

200

{
  "data": {
    "aggregator_details": {
      "aggregator_id": 1,
      "biz_name": "abc",
      "biz_email": "[e-mail]",
      "biz_phone": "08045275677",
      "biz_Address": "abc street, lagos Nigeria",
      "biz_category": "manufacturing",
      "is_active": true,
      "photo": "profile/borrowers/2020/10/07/0.jpg",
      "currency": null
    },
    "borrower_details": {
      "first_name": "Abc",
      "request_firstname": null,
      "last_name": "Xyz",
      "request_lastname": null,
      "gender": null,
      "request_gender": null,
      "date_of_birth": "0001-01-01T00:00:00",
      "request_dob": "0001-01-01T00:00:00",
      "personal_phone": "08132307123911",
      "request_phone": null,
      "kyc_score": null,
      "debt_balance": 110500,
      "available_balance": 0,
      "borrower_id": 116,
      "email": "[e-mail]",
      "borrower_type": null,
      "borrower_type_value": null,
      "my_biz_name": "",
      "my_biz_rc_num": "",
      "total_loan_collected": 0,
      "total_loan_repaid": 0
    },
    "paid_loans": [],
    "product_detail": {
      "id": 17,
      "product_name": "Asset Finance2",
      "product_code": "AF2",
      "interest_rate": "84"
    },
    "okra_details": {
      "okra_account_id": null,
      "okra_bvn": null,
      "okra_customer_id": null,
      "okra_record_id": null
    },
    "borrower_trust_score": 10,
    "retried_disbursement": [],
    "funder_name": "Test Acc Brymo",
    "disbursement_channel_id": null,
    "disbursement_gateway_request": null,
    "disbursement_gateway_response": null,
    "disbursement_gateway_status_id": null,
    "disbursement_response_date_time": null,
    "disbursement_gateway_reference_no": null,
    "disbursement_gateway_final": 0,
    "disbursement_reference_no": null,
    "disbursement_request_date_time": null,
    "loan_id": 18,
    "maker_checker_reference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "loan_interest_amount": 10500,
    "loan_outstanding": 110500,
    "loan_due_date": "2021-05-25T00:00:00",
    "loan_status": "overdue",
    "is_active": false,
    "loan_tenure": 3,
    "loan_amount": 100000,
    "currency": null,
    "loan_amount_repay": 110500,
    "settlement_day": "2020-09-01T00:00:00",
    "has_disburse": false,
    "loan_repayment_balance": 0,
    "loan_ref": "xxxxxxxxxx",
    "has_repaid": false,
    "loan_transfer_status": "pending",
    "disbursement_tag": "",
    "loan_effective_date": "2021-05-22T00:00:00",
    "pub_date": "2020-08-31T07:44:29.435076",
    "modified_date": "2020-08-31T07:44:29.435093",
    "repayment_type": null,
    "repayment_schedule": [
      {
        "repay_schedule_id": 21,
        "pay_date": "2020-09-15T00:00:00",
        "repay_amount": 36833.33
      },
      {
        "repay_schedule_id": 22,
        "pay_date": "2020-10-15T00:00:00",
        "repay_amount": 36833.33
      },
      {
        "repay_schedule_id": 23,
        "pay_date": "2020-11-15T00:00:00",
        "repay_amount": 36833.33
      }
    ],
    "repaid_schedule": null,
    "status": "Submitted_and_awaiting_approval",
    "crc_status": "Failed",
    "crc_score": null,
    "crc_message": "no rcnumber record for borrower account exist for loan f2he3fn1vk",
    "xds_status": "Failed",
    "xds_score": null,
    "xds_message": "no rcnumber record for borrower account exist for loan f2he3fn1vk",
    "sf_status": "Cancelled",
    "sf_score": null,
    "prediction": null
  },
  "message": "Success",
  "status": true,
  "status_code": 200
}