BVN Information Verification

This API allows you to verify that the BVN information supplied by a user matches what is configured on the BVN.

The input to this API is the BVN, expected name on the BVN, date of birth, and mobile number. The API then compares what is supplied to what is actually linked to the BVN and tells you if the supplied input matches or not.

For the date of birth and mobile number fields, an exact comparison is done so you get one of two statuses: a FULL_MATCH or NO_MATCH as the case may be.

For name, a slightly advanced comparison is done and you can get one of three statuses: FULL_MATCH, PARTIAL_MATCH, NO_MATCH.

 

Price

This service costs N10 for each successful request.

 

Endpoint:

POST: https://api.monnify.com/api/v1/vas/bvn-details-match

This endpoint is protected by OAuth 2.0 Bearer Token

 

Please note that the BVN samples used in this documentation are not real and are just indicative of how the API should be used

Scenario 1: Bank Verification Number is not valid

Sample Request:

1 2 3 4 5 6 { "bvn":"22222222226", "name": "Benjamin Ranae RT", "dateOfBirth": "03-Oct-1993", "mobileNo": "08016857829" }

Sample Response:

1 2 3 4 5 { "requestSuccessful": false, "responseMessage": "Unable to process request. Invalid BVN provided", "responseCode": "99" }

 

Scenario 2: Valid Bank Verification Number and Invalid Account Name

Sample Request:

1 2 3 4 5 6 { "bvn":"22222222226", "name": "Benjamin Ranae RT", "dateOfBirth": "03-Oct-1993", "mobileNo": "08016857829" }

Sample Response:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "requestSuccessful": true, "responseMessage": "success", "responseCode": "0", "responseBody": { "bvn": "22222222226", "name": { "matchStatus": "NO_MATCH", "matchPercentage": 0 }, "dateOfBirth": "NO_MATCH", "mobileNo": "NO_MATCH" } }

 

Scenario 3: Specified name partially matches what is on the supplied BVN.

Sample Request:

1 2 3 4 5 6 { "bvn":"22222222226", "name": "OLATUNDE JOSIAH", "dateOfBirth": "03-Oct-1993", "mobileNo": "08016857829" }

Sample Response:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "requestSuccessful": true, "responseMessage": "success", "responseCode": "0", "responseBody": { "bvn": "22222222226", "name": { "matchStatus": "PARTIAL_MATCH", "matchPercentage": 66 }, "dateOfBirth": "NO_MATCH", "mobileNo": "NO_MATCH" } }

 

Scenario 4: Full Match for the Mobile number on the account

Sample Request:

1 2 3 4 5 6 { "bvn":"22222222226", "name": "OLATUNDE JOSIAH OGUNBOYEJO", "dateOfBirth": "27-Apr-1993", "mobileNo": "08142223149" }

 

Sample Response:

100% Full Match On Mobile Number:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "requestSuccessful": true, "responseMessage": "success", "responseCode": "0", "responseBody": { "bvn": "22222222226", "name": { "matchStatus": "FULL_MATCH", "matchPercentage": 100 }, "dateOfBirth": "NO_MATCH", "mobileNo": "FULL_MATCH" } }

 

Field Reference

Field

Description

Status

Field

Description

Status

bvn

11 digit bank verification number expected to belong to the account holder.

Required

mobileNo

11 - 13 digit number expected to belong to the account holder

Required

dateOfBirth

Date of birth of the account holder. The expected format is dd-MMM-yyyy

Required

 

Name matching Rules:

 

Description of Scenario

Sample BVN Names

Sample Account Name

Match Status

 

Description of Scenario

Sample BVN Names

Sample Account Name

Match Status

1.

Name on BVN contains all of names on account number

ABC

CBA

FULL_MATCH

2..

There are at least two matches in BVN or account names

ABC, BC, CD

BCD, AB, AC

PARTIAL_MATCH

3.

There is one match in BVN or account names, or no match at all

ABC

CDE, FGH

NO_MATCH

 

Matching rules for the mobileNo and dateOfBirth fields are exact matches so you either get a value of FULL_MATCH or NO_MATCH as the case may be.