BVN Verification
Learn how to verify customers' BVN.
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 [email protected] 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 their BVN data.
- After approval is granted or declined, the customer will be redirected to the
redirect_urlthat 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.
Making a Request
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 is 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. If no redirect_urlis passed, you will automatically be redirected to Flutterwave’s page after consent is complete. 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 retrieve BVN information 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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"enrollBankCode": null,
"enrollUserName": "[email protected]",
"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
}
}
Testing
- Collect your customer's information (see required information in this step).
- Add the test BVN credential to your request payload, you can use the test data for the consent or no consent flow.
- Send the request to the initiate consent endpoint.
- Select the email option on the NIBSS sandbox consent page* and enter the mock OTP
111111to approve consent for your test. - Confirm redirect back to your provided redirect_URL.
- Check your webhook server for the customer's BVN data.
- Verify the returned BVN data using the verify endpoint.
Updated about 1 month ago