Developer Documentation

{
    "status": "success",
    "response_code": "00",
    "user_data": {
        "nin": "12345678901",
        "first_name": "JOHN",
        "last_name": "DOE",
        "middle_name": "MICHAEL",
        "gender": "MALE",
        "date_of_birth": "15-05-1985",
        "phone_number": "08012345678",
        "address": "123 Sample Street, Lagos"
    },
    "message": "PDF generated successfully",
    "pdf_base64": "base64_encoded_pdf_data_here..."
}

$apiKey = "YOUR_API_KEY_HERE";
$nin = "12345678901"; // your NIN

$url = 'https://checkmybvnnin.com.ng/api/verification/nin_by_nin.php';

// Make API request
$payload = json_encode([
    'api_key' => $apiKey,
    'nin' => $nin
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Content-Length: ' . strlen($payload)
    ]
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);

// Handle response
if ($curlError) {
    echo "API connection failed: " . $curlError;
    exit;
}

$apiResponse = json_decode($response, true);

if ($apiResponse['status'] === 'success' && !empty($apiResponse['pdf_base64'])) {
    // Decode and save PDF
    $pdfData = base64_decode($apiResponse['pdf_base64']);
    $fileName = "nin_slip_" . $nin . ".pdf";
    file_put_contents($fileName, $pdfData);
    echo "PDF saved successfully: " . $fileName;
} else {
    echo "Error: " . $apiResponse['message'];
}

{
    "status": "success",
    "response_code": "00",
    "user_data": {
        "nin": "12345678901",
        "first_name": "JOHN",
        "last_name": "DOE",
        "middle_name": "MICHAEL",
        "gender": "MALE",
        "date_of_birth": "15-05-1985",
        "phone_number": "08012345678",
        "address": "123 Sample Street, Lagos"
    },
    "message": "PDF generated successfully",
    "pdf_base64": "base64_encoded_pdf_data_here..."
}

{
    "status": "success",
    "response_code": "00",
    "user_data": {
        "nin": "12345678901",
        "first_name": "JOHN",
        "last_name": "DOE",
        "middle_name": "MICHAEL",
        "gender": "MALE",
        "date_of_birth": "15-05-1985",
        "phone_number": "08012345678",
        "address": "123 Sample Street, Lagos"
    },
    "message": "PDF generated successfully",
    "pdf_base64": "base64_encoded_pdf_data_here..."
}

$apiKey = "YOUR_API_KEY_HERE";
$firstName = "JOHN";
$lastName = "DOE";
$dob = "1985-05-15"; // yyyy-mm-dd from form
$gender = "MALE";

// Convert DOB from yyyy-mm-dd to dd-mm-yyyy
$formattedDob = date("d-m-Y", strtotime($dob));

$url = 'https://checkmybvnnin.com.ng/api/verification/nin_by_demo.php';

$payload = json_encode([
    'api_key' => $apiKey,
    'firstname' => $firstName,
    'lastname' => $lastName,
    'dob' => $formattedDob,
    'gender' => $gender
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Content-Length: ' . strlen($payload)
    ],
    CURLOPT_SSL_VERIFYPEER => false,
    CURLOPT_SSL_VERIFYHOST => false
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);

if (!empty($curlError)) {
    echo "cURL Error: $curlError";
} elseif ($httpCode !== 200) {
    echo "HTTP Error: $httpCode";
} else {
    $result = json_decode($response, true);
    
    if (!empty($result['pdf_base64'])) {
        $pdfData = base64_decode($result['pdf_base64']);
        $filePath = 'nin_slip_' . time() . '.pdf';
        file_put_contents($filePath, $pdfData);
        echo "PDF saved successfully: $filePath";
    } else {
        echo "Error: " . $result['message'];
    }
}

{
    "status": "success",
    "response_code": "00",
    "user_data": {
        "bvn": "12345678901",
        "first_name": "JOHN",
        "last_name": "DOE",
        "middle_name": "MICHAEL",
        "gender": "MALE",
        "date_of_birth": "15-05-1985",
        "phone_number": "08012345678",
        "address": "123 Sample Street, Lagos"
    },
    "message": "BVN slip generated successfully",
    "pdf_base64": "base64_encoded_pdf_data_here..."
}

{
    "success": true,
    "message": "IPE clearance request submitted successfully. Your request is now pending processing.",
    "data": {
        "transaction_id": "ipe_a1b2c3d4e5f6a1b2c3d4e5f6",
        "tracking_id": "IPE202400001",
        "status": "pending",
        "amount_charged": "500.00",
        "balance_before": "5000.00",
        "balance_after": "4500.00",
        "note": "Your IPE clearance is being processed. You can check the status in your transaction history."
    }
}

HTTP Status: 200 OK

// Insufficient balance
{
    "success": false,
    "message": "Insufficient balance. Your balance is ₦200.00 but IPE clearance costs ₦500.00"
}

// Duplicate tracking ID
{
    "success": false,
    "message": "This tracking ID has already been submitted and is pending processing."
}

// Invalid parameters
{
    "success": false,
    "message": "Invalid trackingID format. Must be 1 to 20 alphanumeric characters."
}

HTTP Status: 400 Bad Request

$apiKey = "YOUR_API_KEY_HERE";
$trackingID = "IPE202400001";

$url = 'https://checkmybvnnin.com.ng/api/verification/ipe.php';

$payload = json_encode([
    'api_key' => $apiKey,
    'trackingID' => $trackingID
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Content-Length: ' . strlen($payload)
    ]
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($result['success'] === true) {
    echo "IPE submitted! Transaction ID: " . $result['data']['transaction_id'];
    echo "Status: " . $result['data']['status'];
    echo "Balance after: ₦" . $result['data']['balance_after'];
} else {
    echo "Error: " . $result['message'];
}