Skip to main content

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

NameTypeRequiredDescription
AuthorizationstringRequiredBearer token with your secret API key
Content-TypestringRequiredMust be application/json

Request Body

bvn
string
required
11-digit Bank Verification Number to verify
BVN must be exactly 11 digits. Leading zeros are significant.
first_name
string
Customer’s first name to match against BVN records (optional but recommended)
last_name
string
Customer’s last name to match against BVN records (optional but recommended)
date_of_birth
string
Customer’s date of birth in YYYY-MM-DD format to match against BVN records
phone_number
string
Customer’s phone number to match against BVN records (in international format)
reference
string
Unique verification reference for tracking purposes
metadata
object
Additional information for the verification request
{
  "customer_id": "12345",
  "verification_type": "account_opening",
  "ip_address": "192.168.1.1",
  "user_agent": "Mozilla/5.0..."
}

Example Request

curl -X POST https://api.payvessel.com/verification/bvn \
  -H "Authorization: Bearer sk_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "bvn": "12345678901",
    "reference": "BVN_VER_2024_001"
  }'

Response

status
string
Request status indicator - "success" or "error"
message
string
Human-readable message describing the result
data
object
BVN verification data object

Example Response

{
  "status": "success",
  "message": "BVN verification successful",
  "data": {
    "bvn": "1234567****",
    "first_name": "JOHN",
    "middle_name": "MICHAEL",
    "last_name": "DOE",
    "full_name": "JOHN MICHAEL DOE",
    "date_of_birth": "1990-05-15",
    "phone_number": "+2348012***678",
    "gender": "Male",
    "marital_status": "Single",
    "nationality": "Nigerian",
    "state_of_origin": "Lagos",
    "lga_of_origin": "Lagos Island",
    "state_of_residence": "Lagos",
    "lga_of_residence": "Victoria Island",
    "residential_address": "15 Victoria Island Road, Lagos",
    "enrollment_bank": "First Bank of Nigeria",
    "enrollment_branch": "Victoria Island",
    "watch_listed": false,
    "image": null,
    "verification_status": "verified",
    "match_results": {
      "first_name_match": true,
      "last_name_match": true,
      "date_of_birth_match": true,
      "phone_number_match": false,
      "overall_match_score": 85
    },
    "reference": "BVN_VER_2024_001",
    "verification_id": "VER_bvn_xyz789abc123",
    "metadata": {
      "customer_id": "12345",
      "verification_type": "loan_application"
    },
    "created_at": "2024-01-15T14:30:00Z"
  }
}

Verification Status Guide

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
Use cases:
  • Account opening approval
  • Loan application processing
  • High-value transaction approval
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
Common causes:
  • Name variations (nicknames, abbreviations)
  • Updated phone number not reflected in BVN
  • Data entry errors
Recommendations:
  • Request customer to provide correct information
  • Consider additional verification methods
  • Implement manual review process
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
Common causes:
  • Incorrect BVN provided
  • BVN deactivated or blocked
  • System downtime
Next steps:
  • Ask customer to verify BVN number
  • Try alternative verification methods
  • Contact support if issue persists

Match Score Interpretation

The overall_match_score helps you understand verification confidence:
High Confidence Match
  • All or most provided data matches exactly
  • Very low fraud risk
  • Proceed with confidence
Typical scenarios:
  • Exact name, DOB, and phone matches
  • Minor variations in address only
  • High-quality data input

Integration Patterns

// KYC verification during account opening
const performKycVerification = async (customerData) => {
  try {
    const bvnVerification = await payvessel.verification.bvn({
      bvn: customerData.bvn,
      first_name: customerData.first_name,
      last_name: customerData.last_name,
      date_of_birth: customerData.date_of_birth,
      phone_number: customerData.phone_number,
      reference: `KYC_${customerData.id}_${Date.now()}`,
      metadata: {
        customer_id: customerData.id,
        verification_type: 'account_opening',
        ip_address: customerData.ip_address
      }
    });
    
    const result = bvnVerification.data;
    
    // Evaluate verification results
    if (result.verification_status === 'verified' && result.match_results.overall_match_score >= 80) {
      await approveAccount(customerData.id);
      return { status: 'approved', verification: result };
    } else if (result.verification_status === 'partial' && result.match_results.overall_match_score >= 60) {
      await flagForManualReview(customerData.id, result);
      return { status: 'review_required', verification: result };
    } else {
      await rejectAccount(customerData.id, 'KYC verification failed');
      return { status: 'rejected', verification: result };
    }
  } catch (error) {
    await handleVerificationError(customerData.id, error);
    throw error;
  }
};

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

Validate Before Sending
  • Ensure BVN is exactly 11 digits
  • Validate date formats (YYYY-MM-DD)
  • Clean phone numbers (international format)
  • Trim whitespace from names
const validateBvn = (bvn) => {
  return /^\d{11}$/.test(bvn);
};

const formatPhoneNumber = (phone) => {
  // Convert 08012345678 to +2348012345678
  if (phone.startsWith('0') && phone.length === 11) {
    return '+234' + phone.substring(1);
  }
  return phone;
};
Graceful Error Management
  • Handle network timeouts gracefully
  • Implement retry logic for temporary failures
  • Log errors for debugging
  • Provide meaningful user feedback
const verifyBvnWithRetry = async (bvnData, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await payvessel.verification.bvn(bvnData);
    } catch (error) {
      if (attempt === maxRetries || error.status === 400) {
        throw error; // Don't retry validation errors
      }
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
    }
  }
};
Efficient Verification
  • Cache verification results (with expiration)
  • Batch process when possible
  • Respect rate limits
  • Use appropriate timeouts
const verificationCache = new Map();

const getCachedVerification = (bvn, expiryMinutes = 60) => {
  const cached = verificationCache.get(bvn);
  if (cached && Date.now() - cached.timestamp < expiryMinutes * 60 * 1000) {
    return cached.data;
  }
  return null;
};

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 detected
  • verification.bvn.watchlist_hit - BVN found on watch list
Rate Limits: BVN verification is limited to 100 requests per minute. Exceeding this limit will result in HTTP 429 responses. Plan your verification flows accordingly.