BVN Verification
Verify Bank Verification Numbers (BVN) to authenticate customer identities and retrieve their registered information from the Nigerian Inter-Bank Settlement System (NIBSS).BVN verification is essential for KYC compliance in Nigeria and helps verify customer identities against official banking records.
Endpoint
POST/verification/bvn
Headers
| Name | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Bearer token with your secret API key |
Content-Type | string | Required | Must be application/json |
Request Body
11-digit Bank Verification Number to verify
Customer’s first name to match against BVN records (optional but recommended)
Customer’s last name to match against BVN records (optional but recommended)
Customer’s date of birth in YYYY-MM-DD format to match against BVN records
Customer’s phone number to match against BVN records (in international format)
Unique verification reference for tracking purposes
Additional information for the verification request
Example Request
Response
Request status indicator -
"success" or "error"Human-readable message describing the result
BVN verification data object
Example Response
Verification Status Guide
verified
verified
Complete VerificationThe BVN exists and all provided data matches the records.Characteristics:
- Valid BVN found in NIBSS database
- High match score (typically > 80%)
- All provided fields match BVN records
- Customer identity is confirmed
- Account opening approval
- Loan application processing
- High-value transaction approval
partial
partial
Partial VerificationThe BVN exists but some provided data doesn’t match the records.Characteristics:
- Valid BVN found in NIBSS database
- Some fields match, others don’t
- Match score between 30-80%
- Manual review may be required
- Name variations (nicknames, abbreviations)
- Updated phone number not reflected in BVN
- Data entry errors
- Request customer to provide correct information
- Consider additional verification methods
- Implement manual review process
failed
failed
Verification FailedThe BVN could not be verified or doesn’t exist.Characteristics:
- BVN not found in NIBSS database
- Technical error during verification
- Invalid BVN format
- Incorrect BVN provided
- BVN deactivated or blocked
- System downtime
- Ask customer to verify BVN number
- Try alternative verification methods
- Contact support if issue persists
Match Score Interpretation
Theoverall_match_score helps you understand verification confidence:
- 90-100% - Excellent
- 70-89% - Good
- 50-69% - Fair
- 0-49% - Poor
High Confidence Match
- All or most provided data matches exactly
- Very low fraud risk
- Proceed with confidence
- Exact name, DOB, and phone matches
- Minor variations in address only
- High-quality data input
Integration Patterns
- Account Opening
- Loan Application
- Transaction Monitoring
- Batch Verification
Compliance & Security
Data Protection
PII Masking: Sensitive data like BVN and phone numbers are automatically masked in responses for security
Regulatory Compliance
CBN Compliance: Adheres to Central Bank of Nigeria guidelines for BVN usage and data handling
Rate Limiting
API Limits: 100 requests per minute to prevent abuse and ensure system stability
Audit Trail
Verification Logs: All verifications are logged with timestamps and references for audit purposes
Best Practices
Input Validation
Input Validation
Validate Before Sending
- Ensure BVN is exactly 11 digits
- Validate date formats (YYYY-MM-DD)
- Clean phone numbers (international format)
- Trim whitespace from names
Error Handling
Error Handling
Graceful Error Management
- Handle network timeouts gracefully
- Implement retry logic for temporary failures
- Log errors for debugging
- Provide meaningful user feedback
Performance Optimization
Performance Optimization
Efficient Verification
- Cache verification results (with expiration)
- Batch process when possible
- Respect rate limits
- Use appropriate timeouts
Related Endpoints
NIN Verification
Verify National Identity Numbers for enhanced KYC
Face Comparison
Compare customer photos with BVN records
Liveness Detection
Ensure customer photos are from live subjects
Phone Verification
Verify phone numbers via SMS or voice calls
Webhook Events
This endpoint triggers the following webhook events:verification.bvn.completed- BVN verification completed (success or failure)verification.bvn.match_found- High confidence match detectedverification.bvn.watchlist_hit- BVN found on watch list
