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:
- To enable the feature that resolves BVN information, please send an email to hi@flutterwavego.com requesting approval.
- Send the customer's name and BVN to the initiate-consent endpoint. It will return a hosted page.
- Redirect the customer to the consent page to provide approval to access to their BVN data.
- 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.
Initiate owner's consent
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.
There are two possible scenarios for the consent initiation response:
- The customer gives consent to the merchant for the first time: In this case,
data.redirect_urlreturns a valid url. - The customer has given consent to the merchant in the past: This scenario can lead to two different responses:
- A null redirect url returned in the response as
data.redirect_url. - The redirect url pointing to the merchant's redirect url.
- A null redirect url returned in the response as
In both cases, the customer doesn't need to verify the consent request and can simply retrieve the BVN information using the request reference.
{
"status": "success",
"message": "Bvn verification initiated",
"data": {
"url": "https://nibss-bvn-consent-management.myflutterwave.com/cms/BvnConsent?session=MWQzYWYxOWYtMWE1MS00MTdhLWFlMzEtNjEwNDgzZGQ0ZDFi",
"reference": "FLW0B0BCB7D3F8A1148C87232"
}
}
{
"success": true,
"data": {
"url": null,
"reference": "FLW36C15AD***************"
},
"message": "Bvn verification initiated",
"error": []
}
{
"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
}
}