Integration Guide

Overview

Our BVN lookup integration allows you to initiate, verify, and fetch details associated with a Bank Verification Number (BVN) using Mono's API. Follow the steps below to seamlessly integrate this functionality into your application.

Prerequisites

To get started, please ensure to:

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

Step 1: Initiate BVN Lookup

This API call initiates a BVN consent request by providing the BVN value. 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"
  }' \
  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***[email protected]"
      },
      {
        "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 BVN 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": "Otp has been successfully sent to your alternate phone number"
}

Step 3: Fetch BVN Details

This API call retrieves the BVN details by passing the OTP received on the user's end. 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 BVN 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

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

{
  "status": "successful",
  "message": "BVN details successfully fetched.",
  "data": {
    "firstName": "Foo",
    "middleName": "",
    "lastName": "Bar",
    "dob": "1906-09-05",
    "phoneNumber1": "08057438543",
    "phoneNumber2": null,
    "registrationDate": "2018-03-26",
    "email": "[email protected]",
    "gender": "male",
    "lgaOforigin": "Abeokuta South",
    "lgaOfResidence": "Ikeja",
    "maritalStatus": "single",
    "nin": "0000000000",
    "stateOfOrigin": "Ogun State",
    "stateOfResidence": "Lagos State",
    "watchListed": false,
    "photoId": "/JC4nICIIyMjIyMjIyMjL/wAARCAGQASw7NAH//2Q=="
  }
}