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

{
  "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

{
    "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.

{
  "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

{
    "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)

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

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

{
  "data": {
    "aggregator_details": {
      "aggregator_id": 1,
      "biz_name": "abc",
      "biz_email": "abc@xyz.com",
      "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": "abc@xyz.com",
      "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
}

PreviousAuthentication and AuthorisationNextWallet

Last updated