Skip to main content
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
api-keystringRequiredYour 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 "api-key: YOUR_API_KEY" \
  -H "api-secret: YOUR_SECRET" \
  -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;
};

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 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.