BVN Lookup Integration Guide

Overview

Our BVN lookup integration leverages the NIBSS iGree consent platform to enable retrieve your customers’ BVN details or bank accounts associated with their BVN, with their consent. To effortlessly incorporate this feature into your application, please follow the steps outlined below.

Prerequisites

To get started, please ensure to:

• Sign up on the Mono Dashboard.
• Create an App and fetch the generated Secret Key.

Integration Steps

With the above prerequisite steps taken, please note that there are three stages for completing the integration process:

1. Initiate Lookup: At this stage, your user must grant consent for the BVN lookup by providing their BVN ID. Depending on the desired extent of the BVN lookup, you have two options: passing "identity" as the scope to retrieve identity details or “bank_accounts” to retrieve all bank accounts associated with the user’s BVN.

2. Verify OTP: In this step, you should submit the user’s chosen verification method as indicated in the response from the previous stage.

3. Fetch Details: You will need to supply the OTP sent to the user to access the information (either BVN Details or Bank accounts), depending on the scope specified during the initiation process.

Step 1: Initiate Lookup

This API call initiates a BVN consent request by providing the BVN value and scope (if necessary). The bvn value should be passed as a required field in the request body. Upon successful initiation, the API will respond with a session ID and available verification methods.

To initiate a BVN lookup, send a POST request to the following endpoint:

POST https://api.withmono.com/v2/lookup/bvn/initiate

Request Body Parameters

• bvn (required): The Bank Verification Number (BVN) you want to look up.

cURL Sample Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "mono-sec-key: YOUR_MONO_SECRET_KEY" \
  -d '{
    "bvn": "12345678901"
    "scope": "bank_accounts" // or identity
  }' \
  https://api.withmono.com/v2/lookup/bvn/initiate

Success Response

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

{
  "status": "successful",
  "message": "BVN Lookup successfully initiated.",
  "data": {
    "session_id": "74c8fe70-ea2c-458e-a99f-3f7a6061632c",
    "methods": [
      {
        "method": "email",
        "hint": "An email with a verification code will be sent to tomi***jr@gmail.com"
      },
      {
        "method": "phone",
        "hint": "Sms with a verification code will be sent to phone 0818***6496"
      },
      {
        "method": "phone_1",
        "hint": "Sms with a verification code will be sent to phone 0818***9343"
      },
      {
        "method": "alternate_phone",
        "hint": "Sms with a verification code will be sent to your alternate phone number"
      }
    ]
  }
}

Step 2: Verify OTP

This API call verifies the BVN using the OTP received by the user. You need to pass the method field with the chosen verification method and, if alternate_phone is selected, you must include the phone_number field with the associated phone number. Make sure to include the x-session-id header with the session ID received from Step 1.

To verify the BVN using the One-Time Password (OTP) received by the user, send a POST request to the following endpoint:

POST https://api.withmono.com/v2/lookup/bvn/verify

Request Body Parameters

• method (required): The verification method. Choose from "phone", "phone_1", "alternate_phone", or "email".
• phone_number (required for method=alternate_phone): The phone number associated with the alternate verification method.

cURL Sample Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "mono-sec-key: YOUR_MONO_SECRET_KEY" \
  -H "x-session-id: SESSION_ID_FROM_STEP_1" \
  -d '{
    "method": "alternate_phone",
    "phone_number": "08123456789"
  }' \
  https://api.withmono.com/v2/lookup/bvn/verify

Success Response

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

{
    "status": "successful",
    "message": "Please enter the OTP that was sent to 09066662020",
    "timestamp": "2024-05-06T14:28:01.988Z",
    "data": null
}

Step 3: Fetch Details

This stage retrieves either the BVN Details or Bank accounts, depending on the scope specified during the initiation process. Include the otp field in the request body. Make sure to include the x-session-id header with the session ID received from Step 1.

To fetch the details, send a POST request to the following endpoint:

POST https://api.withmono.com/v2/lookup/bvn/details

Request Body Parameters

• otp (required): The One-Time Password (OTP) received by the user.

cURL Sample Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "mono-sec-key: YOUR_MONO_SECRET_KEY" \
  -H "x-session-id: SESSION_ID_FROM_STEP_1" \
  -d '{
    "otp": "123456"
  }' \
  https://api.withmono.com/v2/lookup/bvn/details

Success Response (when scope is Identity)

If the request is successful and the scope during the BVN intiation was identity, you will receive the following response:

{
  "status": "successful",
  "message": "BVN details successfully fetched.",
  "timestamp": "2024-04-30T09:44:04.577Z",
  "data": {
    "first_name": "Samuel",
    "last_name": "Olamide",
    "middle_name": "Nomo",
    "dob": "2020-01-06",
    "phone_number": "08012345616",
    "phone_number_2": null,
    "email": "nomo@test.com",
    "gender": "Male",
    "state_of_origin": "Lagos State",
    "bvn": "12345678901",
    "nin": "000000000",
    "registration_date": "2020-01-06",
    "lga_of_origin": "yaba",
    "lga_of_Residence": "yaba",
    "marital_status": "single",
    "watch_listed": true,
    "photoId": "image_base64"
  }
}

Success Response (when scope is Bank Accounts)

If the request is successful and the scope during the BVN intiation was bank_accounts , you will receive the following response:

{
  "status": "successful",
  "message": "BVN bank accounts successfully fetched.",
  "timestamp": "2024-05-06T14:33:54.508Z",
  "data": [
    {
      "account_name": "Samuel Olamide",
      "account_number": "1234567890",
      "account_type": "SAVINGS",
      "account_designation": "OTHERS",
      "institution": {
          "name": "First Bank",
          "branch": "4659818",
          "bank_code": "011"
      }
    },
    {
      "account_name": "Olamide Samuel",
      "account_number": "1234509384",
      "account_type": "CURRENT",
      "account_designation": "OTHERS",
      "institution": {
          "name": "Zenith Bank",
          "branch": "4661483",
          "bank_code": "00711"
      }
    }
  ]
}