Bvnverification

BVN Verification

Verify customer identities against Nigeria's Bank Verification Number (BVN) database. Match personal details like name, date of birth, phone number, and gender to ensure your customers are who they say they are.

Endpoint

POST https://api.budpay.com/api/v2/bvn/verify

Quick Start

curl https://api.budpay.com/api/v2/bvn/verify \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
    "bvn": "00000000000",
    "first_name": "Tolulope",
    "middle_name": "Samuel",
    "last_name": "Segun",
    "phone_number": "08011111111",
    "dob": "1972-12-03",
    "gender": "Male",
    "reference": "20220540300003938",
    "callback_url": "http://your_webhook_url"
}' \
-X POST

Response

{
    "success": true,
    "message": "Request Submitted Successfully",
    "reference": "20220540300003938"
}

Request Parameters

Headers

Header	Description	Required
Authorization	`Bearer YOUR_SECRET_KEY`	Yes
Content-Type	`application/json`	Yes

Body

Parameter	Type	Required	Description
`bvn`	String	Yes	11-digit BVN to verify. Use `00000000000` for testing
`callback_url`	String	Yes	Your webhook URL to receive verification results
`first_name`	String	No	First name to match against BVN record
`middle_name`	String	No	Middle name to match against BVN record
`last_name`	String	No	Last name to match against BVN record
`phone_number`	String	No	Phone number to match against BVN record
`dob`	String	No	Date of birth in `YYYY-MM-DD` format
`gender`	String	No	Gender: `Male` or `Female`
`reference`	String	No	Your unique reference (auto-generated if not provided)

Response Fields

Field	Type	Description
`success`	Boolean	`true` if request was submitted successfully
`message`	String	Human-readable response message
`reference`	String	Unique reference to track this verification

Webhook Response

Once verification is complete, BudPay sends the results to your callback_url:

{
    "success": true,
    "message": "BVN verification completed",
    "reference": "20220540300003938",
    "data": {
        "bvn": "00000000000",
        "first_name": "Tolulope",
        "middle_name": "Samuel",
        "last_name": "Segun",
        "phone_number": "08011111111",
        "dob": "1972-12-03",
        "gender": "Male",
        "matches": {
            "first_name": true,
            "middle_name": true,
            "last_name": true,
            "phone_number": true,
            "dob": true,
            "gender": true
        }
    }
}

The matches object shows whether each field you provided matches the BVN record — perfect for KYC compliance checks.

Try It Out

Error Responses

Invalid BVN Format (400)

{
    "success": false,
    "message": "Invalid BVN format"
}

Unauthorized (401)

{
    "success": false,
    "message": "Authentication failed"
}

Validation Error (422)

{
    "success": false,
    "message": "Validation error",
    "errors": {
        "bvn": ["The bvn field is required"],
        "callback_url": ["The callback url field is required"]
    }
}

Best Practices

Include matching fields (name, phone, DOB) to get a comprehensive verification report. The more fields you include, the stronger your identity verification.

Use Test BVN — Use 00000000000 when testing in sandbox mode
Secure Your Webhook — Ensure your callback URL is accessible and handles POST requests
Match More Fields — Include all available matching fields for thorough verification
Track References — Use unique references to link verification results to your records
Verify Webhook Source — Always confirm callback authenticity before processing
Handle Asynchronously — BVN verification is async; design your flow accordingly

Security

⚠️

BVN is highly sensitive personal data. Never expose BVN in client-side code, logs, or error messages. Always use HTTPS.

HTTPS Only — Encrypt all API communication
Server-Side Only — Never request BVN verification from the frontend
Comply with Regulations — Follow NDPR and other data protection laws
Encrypt at Rest — If you must store BVN data, encrypt it
Restrict Access — Limit who can trigger BVN verifications
Maintain Audit Logs — Track all verification requests for compliance

Verify Account Number Overview