bvn-verification/bvn-verification-php

A PHP package for Nigerian BVN verification through NIBSS NPS - Perfect for Laravel, Symfony, and any PHP project

1.0.0 2025-11-11 20:48 UTC

Requires

• php: ^7.4|^8.0
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• orchestra/testbench: ^6.0|^7.0
• phpunit/phpunit: ^9.0

MIT

• Bazeet Alli (Bazzlycodes)

• identity
• laravel
• verification
• Nigeria
• fintech
• kyc
• nibss
• bvn

README

A professional PHP package for Nigerian Bank Verification Number (BVN) verification through NIBSS NPS API. Perfect for Laravel, Symfony, and any PHP project requiring secure identity verification.

🚀 Quick Start

Installation

composer require bvn-verification/bvn-verification-php

Basic Usage

<?php

require 'vendor/autoload.php';

use BVNVerification\BVNVerifier;

// Initialize verifier (mock mode for testing)
$verifier = new BVNVerifier('your-api-key', true, 'json-mock');

// Verify BVN
$result = $verifier->verify('12345678901', 'JOHN DOE');

if ($result->isMatch()) {
    echo "✅ BVN verified successfully!";
    echo "Registered Name: " . $result->getVerifiedName();
} else {
    echo "❌ Verification failed: " . $result->message;
}

📦 Installation

For Laravel Projects

1. Install the package:

composer require bvn-verification/bvn-verification-php

1. Publish configuration (optional):

php artisan vendor:publish --provider="BVNVerification\\Laravel\\BVNVerificationServiceProvider"

1. Configure environment variables in .env:

BVN_VERIFICATION_API_KEY=your-api-key-here
BVN_VERIFICATION_SANDBOX_MODE=true
BVN_VERIFICATION_MODE=json-mock

For Standalone PHP Projects

composer require bvn-verification/bvn-verification-php

⚙️ Configuration

Laravel Configuration

After installation, add to your .env file:

# For production with NIBSS API
BVN_VERIFICATION_API_KEY=your-real-nibss-key
BVN_VERIFICATION_SANDBOX_MODE=false
BVN_VERIFICATION_MODE=live

# For development/testing
BVN_VERIFICATION_API_KEY=mock-key
BVN_VERIFICATION_SANDBOX_MODE=true
BVN_VERIFICATION_MODE=json-mock

Manual Configuration

use BVNVerification\BVNVerifier;

// Production mode (real NIBSS API)
$verifier = new BVNVerifier(
    'your-nibss-api-key',  // API key from NIBSS
    false,                 // sandbox mode (false for production)
    'live'                 // mode: 'live' for real API
);

// Development mode (mock data)
$verifier = new BVNVerifier(
    'mock-key',            // any string for mock mode
    true,                  // sandbox mode (true for testing)
    'json-mock'            // mode: 'json-mock' for mock data
);

🎯 Usage Examples

Laravel Usage

Using Facade:

<?php

namespace App\Http\Controllers;

use BVNVerification\Laravel\Facades\BVNVerifier;

class VerificationController extends Controller
{
    public function verifyCustomer(Request $request)
    {
        $result = BVNVerifier::verify($request->bvn, $request->full_name);
        
        return response()->json([
            'verified' => $result->isMatch(),
            'registered_name' => $result->getVerifiedName(),
            'message' => $result->message
        ]);
    }
}

Using Dependency Injection:

<?php

namespace App\Http\Controllers;

use BVNVerification\BVNVerifier;

class VerificationController extends Controller
{
    public function verifyCustomer(Request $request, BVNVerifier $verifier)
    {
        $result = $verifier->verify($request->bvn, $request->full_name);
        
        if ($result->isMatch()) {
            // Proceed with verified user
            return redirect('/dashboard')->with('success', 'BVN verified!');
        }
        
        return back()->with('error', 'BVN verification failed: ' . $result->message);
    }
}

Standalone PHP Usage

Basic Verification:

<?php

require 'vendor/autoload.php';

use BVNVerification\BVNVerifier;

$verifier = new BVNVerifier('mock-key', true, 'json-mock');

$customers = [
    ['bvn' => '12345678901', 'name' => 'JOHN DOE'],
    ['bvn' => '98765432109', 'name' => 'JANE SMITH'],
    ['bvn' => '12345678901', 'name' => 'WRONG NAME'] // This will fail
];

foreach ($customers as $customer) {
    $result = $verifier->verify($customer['bvn'], $customer['name']);
    
    echo "BVN: {$customer['bvn']}\n";
    echo "Name: {$customer['name']}\n";
    echo "Status: " . ($result->isMatch() ? 'VERIFIED' : 'FAILED') . "\n";
    
    if ($result->getVerifiedName()) {
        echo "Registered Name: {$result->getVerifiedName()}\n";
    }
    
    echo "Message: {$result->message}\n";
    echo "------------------------\n";
}

Batch Processing:

<?php

require 'vendor/autoload.php';

use BVNVerification\BVNVerifier;

class BVNService
{
    private $verifier;
    
    public function __construct()
    {
        $this->verifier = new BVNVerifier('mock-key', true, 'json-mock');
    }
    
    public function processBatch(array $applications): array
    {
        $results = [];
        
        foreach ($applications as $app) {
            try {
                $result = $this->verifier->verify($app['bvn'], $app['full_name']);
                
                $results[] = [
                    'application_id' => $app['id'],
                    'bvn' => $app['bvn'],
                    'verified' => $result->isMatch(),
                    'registered_name' => $result->getVerifiedName(),
                    'status' => $result->status,
                    'message' => $result->message,
                    'timestamp' => date('Y-m-d H:i:s')
                ];
            } catch (Exception $e) {
                $results[] = [
                    'application_id' => $app['id'],
                    'bvn' => $app['bvn'],
                    'verified' => false,
                    'error' => $e->getMessage(),
                    'timestamp' => date('Y-m-d H:i:s')
                ];
            }
        }
        
        return $results;
    }
}

// Usage
$service = new BVNService();
$applications = [
    ['id' => 1, 'bvn' => '12345678901', 'full_name' => 'JOHN DOE'],
    ['id' => 2, 'bvn' => '98765432109', 'full_name' => 'JANE SMITH'],
];

$results = $service->processBatch($applications);
print_r($results);

🔧 API Reference

Core Methods

verify(string $bvn, string $customerName): VerificationResponse

Verifies a BVN against the provided name.

$result = $verifier->verify('12345678901', 'JOHN DOE');

if ($result->isMatch()) {
    // Verification successful
    $registeredName = $result->getVerifiedName();
} else {
    // Verification failed
    $errorMessage = $result->message;
}

verifyWithDetails(string $bvn, string $customerName): VerificationResponse

Alias of verify() - provides the same functionality.

Response Object

The VerificationResponse object contains:

• isMatch(): bool - Whether BVN and name match
• getVerifiedName(): ?string - Registered name from BVN records
• status: string - Verification status ('completed', 'failed')
• message: ?string - Additional information or error message

Utility Methods

getBVNRecords(): array (Mock mode only)

Returns all available BVN records from mock data.

if ($verifier->supportsBVNRecords()) {
    $records = $verifier->getBVNRecords();
    foreach ($records as $record) {
        echo "BVN: {$record['bvn']} - Name: {$record['registered_name']}\n";
    }
}

supportsBVNRecords(): bool

Checks if BVN records are available (only in JSON mock mode).

setMode(string $mode): void

Switch between operation modes.

$verifier->setMode('live'); // Switch to live NIBSS API
$verifier->setMode('json-mock'); // Switch back to mock mode

setSandboxMode(bool $enabled): void

Toggle sandbox mode.

$verifier->setSandboxMode(false); // Disable sandbox (production)

🎪 Mock Data

Using Built-in Mock Data

The package includes sample BVN data for testing:

$verifier = new BVNVerifier('any-key', true, 'json-mock');

// Test with sample data
$testCases = [
    ['12345678901', 'JOHN DOE'],     // ✅ Match
    ['98765432109', 'JANE SMITH'],   // ✅ Match  
    ['12345678901', 'WRONG NAME'],   // ❌ Mismatch
    ['00000000000', 'ANY NAME'],     // ❌ BVN not found
];

foreach ($testCases as $test) {
    $result = $verifier->verify($test[0], $test[1]);
    // Process results...
}

Custom Mock Data

Create your own JSON file:

{
  "bvn_records": [
    {
      "bvn": "11122233344",
      "registered_name": "CHUKWUMA OKORO",
      "first_name": "Chukwuma",
      "last_name": "Okoro",
      "phone": "08011122233",
      "email": "[e-mail]"
    },
    {
      "bvn": "55566677788", 
      "registered_name": "MUSA ABDULLAHI",
      "first_name": "Musa",
      "last_name": "Abdullahi",
      "phone": "08055566677",
      "email": "[e-mail]"
    }
  ]
}

🔐 Production Setup

1. Get NIBSS Credentials

Apply for NIBSS NPS API access at NIBSS Plc.

2. Configure for Production

Laravel (.env):

BVN_VERIFICATION_API_KEY=your-production-api-key
BVN_VERIFICATION_SANDBOX_MODE=false
BVN_VERIFICATION_MODE=live

Standalone PHP:

$verifier = new BVNVerifier(
    'your-production-api-key',
    false, // sandbox mode OFF
    'live' // live mode
);

3. Error Handling in Production

try {
    $result = $verifier->verify($bvn, $customerName);
    
    if ($result->isMatch()) {
        // Success - proceed with verified user
        $this->createUserAccount($customerData);
    } else {
        // Verification failed
        throw new Exception('BVN verification failed: ' . $result->message);
    }
} catch (\BVNVerification\Exceptions\VerificationException $e) {
    // Handle verification-specific errors
    Log::error('BVN Verification Error: ' . $e->getMessage());
    return response()->json(['error' => 'Verification service unavailable'], 503);
} catch (\Exception $e) {
    // Handle other errors
    Log::error('BVN Service Error: ' . $e->getMessage());
    return response()->json(['error' => 'Service temporarily unavailable'], 500);
}

🚨 Error Handling

Common Scenarios

Invalid BVN Format:

try {
    $result = $verifier->verify('123', 'John Doe'); // Too short
} catch (\BVNVerification\Exceptions\VerificationException $e) {
    echo "Error: " . $e->getMessage(); // "BVN must be exactly 11 digits"
}

API Connection Issues:

try {
    $result = $verifier->verify('12345678901', 'John Doe');
} catch (\BVNVerification\Exceptions\AuthenticationException $e) {
    // Invalid API key or authentication failed
    Log::error('Authentication failed: ' . $e->getMessage());
} catch (\BVNVerification\Exceptions\VerificationException $e) {
    // Other verification errors
    Log::error('Verification error: ' . $e->getMessage());
}

Best Practices

public function verifyCustomerBVN($bvn, $customerName)
{
    try {
        // Validate input first
        if (empty($bvn) || empty($customerName)) {
            throw new InvalidArgumentException('BVN and customer name are required');
        }
        
        // Perform verification
        $result = $this->verifier->verify($bvn, $customerName);
        
        // Log the attempt
        Log::info('BVN verification attempted', [
            'bvn' => $bvn,
            'provided_name' => $customerName,
            'verified' => $result->isMatch(),
            'registered_name' => $result->getVerifiedName()
        ]);
        
        return $result;
        
    } catch (\BVNVerification\Exceptions\VerificationException $e) {
        Log::error('BVN verification service error', [
            'bvn' => $bvn,
            'error' => $e->getMessage()
        ]);
        throw new ServiceUnavailableException('Verification service temporarily unavailable');
    } catch (Exception $e) {
        Log::error('Unexpected BVN verification error', [
            'bvn' => $bvn,
            'error' => $e->getMessage()
        ]);
        throw $e;
    }
}

🧪 Testing

Laravel Tests

<?php

namespace Tests\Feature;

use Tests\TestCase;
use BVNVerification\Laravel\Facades\BVNVerifier;

class BVNVerificationTest extends TestCase
{
    public function test_successful_bvn_verification()
    {
        $result = BVNVerifier::verify('12345678901', 'JOHN DOE');
        
        $this->assertTrue($result->isMatch());
        $this->assertEquals('JOHN DOE', $result->getVerifiedName());
    }
    
    public function test_failed_bvn_verification()
    {
        $result = BVNVerifier::verify('12345678901', 'WRONG NAME');
        
        $this->assertFalse($result->isMatch());
        $this->assertStringContainsString('does not match', $result->message);
    }
    
    public function test_invalid_bvn_format()
    {
        $this->expectException(\BVNVerification\Exceptions\VerificationException::class);
        
        BVNVerifier::verify('123', 'John Doe');
    }
}

Standalone PHP Tests

<?php

require 'vendor/autoload.php';

use BVNVerification\BVNVerifier;

class BVNVerificationTest
{
    private $verifier;
    
    public function setUp()
    {
        $this->verifier = new BVNVerifier('test-key', true, 'json-mock');
    }
    
    public function testVerification()
    {
        $result = $this->verifier->verify('12345678901', 'JOHN DOE');
        
        assert($result->isMatch() === true, 'Should verify successfully');
        assert($result->getVerifiedName() === 'JOHN DOE', 'Should return registered name');
        
        echo "✅ All tests passed!\n";
    }
}

$test = new BVNVerificationTest();
$test->setUp();
$test->testVerification();

📋 Common Use Cases

E-commerce Registration

public function registerCustomer(Request $request)
{
    $validated = $request->validate([
        'bvn' => 'required|digits:11',
        'full_name' => 'required|string|min:2',
        'email' => 'required|email',
        'phone' => 'required|string'
    ]);
    
    // Verify BVN
    $verificationResult = BVNVerifier::verify(
        $validated['bvn'], 
        $validated['full_name']
    );
    
    if (!$verificationResult->isMatch()) {
        return back()->withErrors([
            'bvn' => 'BVN verification failed. Please ensure your BVN and name match your bank records.'
        ]);
    }
    
    // Create customer account
    $customer = Customer::create([
        'bvn' => $validated['bvn'],
        'verified_name' => $verificationResult->getVerifiedName(),
        'email' => $validated['email'],
        'phone' => $validated['phone'],
        'bvn_verified_at' => now()
    ]);
    
    return redirect('/dashboard')->with('success', 'Account created successfully!');
}

Loan Application

public function submitLoanApplication(Request $request)
{
    $verificationResult = BVNVerifier::verify(
        $request->bvn,
        $request->full_name
    );
    
    if ($verificationResult->isMatch()) {
        $application = LoanApplication::create([
            'user_id' => auth()->id(),
            'bvn' => $request->bvn,
            'verified_name' => $verificationResult->getVerifiedName(),
            'amount' => $request->amount,
            'status' => 'under_review'
        ]);
        
        return response()->json([
            'success' => true,
            'application_id' => $application->id,
            'message' => 'Loan application submitted for review'
        ]);
    }
    
    return response()->json([
        'success' => false,
        'message' => 'BVN verification failed. Please check your details.'
    ], 422);
}

🔗 Support

• Documentation: GitHub Repository
• Issues: GitHub Issues
• Email: [e-mail]

📄 License

This package is open-source software licensed under the MIT license.

Ready to verify identities securely? 🚀

Get started today and integrate BVN verification into your PHP applications in minutes!