BVN verification

In Nigeria, Bank Verification Numbers (BVNs) are commonly used to verify customers during Know Your Customer (KYC) checks. As mandated by the Central Bank of Nigeria, we expect merchants to obtain customer consent prior to accessing their BVN. This helps protect customers from BVN misuse, making it safer for customers to share their BVN details with merchants.

How does this work?

To securely access your customers' BVN information correctly, follow these steps:

  1. To enable the feature that resolves BVN information, please send an email to hi@flutterwavego.com requesting approval.
  2. Send the customer's name and BVN to the initiate-consent endpoint. It will return a hosted page.
  3. Redirect the customer to the consent page to provide approval to access to their BVN data.
  4. After approval is granted or declined, the customer will be redirected to the redirect_url that was passed in step 1. You can then query the verify consent endpoint to retrieve the customer's BVN information.

Before obtaining a customer's BVN details, you must first obtain their consent. To initiate consent, pass the customer's full_name, bvn, and redirect_url to the initiate consent endpoint.

BVNs are 11 digits. Ensure that you are sending them in this format to prevent validation errors.

// https://api.flutterwave.com//v3/bvn/verifications
{
    "bvn": "123478322",
    "firstname": "Lyra",
    "lastname": "Balacqua",
    "redirect_url": "https://example-url.company.com"
}

For successful calls, we will return a response that includes a redirect link and a reference for the consent request. The redirect link generated can only be used once. Failed calls will return validation errors.

If a user has previously given consent to resolve their BVN, the redirect link generated in the response will redirect to the URL specified as redirect_url. To verify the consent, simply use the reference.

{
    "status": "success",
    "message": "Bvn verification initiated",
    "data": {
        "url": "https://nibss-bvn-consent-management.myflutterwave.com/cms/BvnConsent?session=MWQzYWYxOWYtMWE1MS00MTdhLWFlMzEtNjEwNDgzZGQ0ZDFi",
        "reference": "FLW0B0BCB7D3F8A1148C87232"
    }
}
{
    "status": "error",
    "message": "bvn length must be 11 characters long",
    "data": null
}

After being redirected, the customer must enter their BVN, confirm their consent with a token, and select which information to share with the merchant.

Retrieving BVN Information

After a customer gives consent on the NIBSS portal, they will be redirected to your redirect_url. To obtain the customer's BVN information, you must call the verify endpoint with the reference returned in the response of the initiate consent API call.

To retrieve BVN data, you should listen for webhooks to receive the data when it becomes available. Alternatively, you can poll the verify consent endpoint.

{
  "status": "success",
  "message": "Bvn details fetched",
  "data": {
      "first_name": "LYRA",
      "last_name": "Balacqua",
      "status": "COMPLETED",
      "reference": "FLW441BD872AEBB28BD53B239",
      "callback_url": null,
      "bvn_data": {
        "nin": "485xxxxxx33",
        "email": "test-user@example.com",
        "gender": "Male",
        "surname": "Balacqua",
        "serialNo": null,
        "faceImage": "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",
        "firstName": "LYRA ",
        "landmarks": null,
        "branchName": null,
        "middleName": "USER ",
        "nameOnCard": null,
        "dateOfBirth": "199x-05-xxT23:00:00Z",
        "lgaOfOrigin": "Test lga",
        "watchlisted": "0.0",
        "lgaOfCapture": null,
        "phoneNumber1": "234810xxxx188",
        "phoneNumber2": null,
        "maritalStatus": "Single",
        "stateOfOrigin": "Lagos State",
        "enrollBankCode": null,
        "enrollUserName": "user@example.com",
        "enrollmentDate": null,
        "lgaOfResidence": "Ikorodu",
        "stateOfCapture": "Lagos State",
        "additionalInfo1": null,
        "productReference": "FLW441BD872AEBB28BD53B239",
        "stateOfResidence": "Lagos State"
      },
      "created_at": "2023-04-13T23:02:23.000Z"
    }
}
{
  "event": "bvn.completed",
  "event.type": "BVN",
  "data": {
    "id": 18,
    "reference": "FLW441BD872AEBB28BD53B239",
    "status": "COMPLETED",
    "firstname": "LYRA",
    "lastname": "Balacqua",
    "callback_url": "https://webhook.site/939e641f-e477-4b1d-af3a-1ee9bbbd1181",
    "AccountId": 35308,
    "bvn_data": {
      "additionalInfo1": null,
      "branchName": null,
      "dateOfBirth": "199x-05-xxT23:00:00Z",
      "email": "test-user@example.com",
      "enrollBankCode": null,
      "enrollUserName": "user@example.com",
      "enrollmentDate": null,
      "faceImage": "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",
      "firstName": "LYRA ",
      "gender": "Male",
      "landmarks": null,
      "lgaOfCapture": null,
      "lgaOfOrigin": "Test lga",
      "lgaOfResidence": "Ikorodu",
      "maritalStatus": "Single",
      "middleName": "USER ",
      "nameOnCard": null,
      "nin": "485xxxxxx33",
      "phoneNumber1": "234810xxxx188",
      "phoneNumber2": null,
      "productReference": "FLW441BD872AEBB28BD53B239",
      "serialNo": null,
      "stateOfCapture": "Lagos State",
      "stateOfOrigin": "Lagos State",
      "stateOfResidence": "Lagos State",
      "surname": "Balacqua",
      "watchlisted": "0.0"
    },
    "createdAt": "2023-04-13T23:02:23.000Z",
    "updatedAt": "2023-04-13T23:06:18.000Z",
    "deletedAt": null
  }
}
Loading...