Identity Verification (BVN/NIN)

Verify the identity of your customers using their Bank Verification Number (BVN) or National Identity Number (NIN). HwebPay provides a simple OTP-based verification flow that securely confirms the identity against central databases.

Verification Fee: A standard fee of NGN 50.00 is charged per verification request directly to your available wallet balance. Ensure you have sufficient balance before initiating a request.

The Verification Flow

Identity verification is a two-step process:

Initiate: Send the ID number (e.g. BVN). The system will send an OTP to the customer's registered phone number.
Validate: Submit the OTP to complete the verification and retrieve the customer details.

1. Initiate Verification

Initiate an identity verification request. We provide convenient aliases specifically for BVN, but you can also use the general identity endpoints.

HTTP Request POST

POST https://api.hwebpay.com/api/v1/bvn/verify
Authorization: Bearer YOUR_SECRET_KEY
Content-Type: application/json

# Or generic identity endpoint
POST https://api.hwebpay.com/api/v1/identity/verify

Request Payload

Parameter	Type	Description
type	String	The ID type. Valid options: `BVN`, `NIN`
number	String	The 11-digit BVN or NIN to verify.

Example Response

{
    "status": "success",
    "message": "Verification initiated. OTP sent to customer.",
    "verification_id": "64a2b1...c9f1",
    "provider_response": {
        "_id": "64a2b1...c9f1",
        "status": "Pending"
    }
}

2. Validate OTP

Once the customer receives the OTP, validate it to get the identity details.

HTTP Request POST

POST https://api.hwebpay.com/api/v1/bvn/validate
Authorization: Bearer YOUR_SECRET_KEY
Content-Type: application/json

# Or generic identity endpoint
POST https://api.hwebpay.com/api/v1/identity/validate

Request Payload

Parameter	Type	Description
verification_id	String	The `_id` returned from the initiate step.
type	String	Must match the type used in initiation (e.g. `BVN`).
otp	String	The OTP provided by the customer.

Example Response

{
    "status": "success",
    "message": "Identity verified successfully",
    "data": {
        "_id": "690c61c68d3d86c9e8b3cacd",
        "clientId": "6874eb47aaad890024be3930",
        "identityNumber": "12345678901",
        "type": "BVN",
        "amount": 50,
        "status": "SUCCESS",
        "debitAccountNumber": "0106664982",
        "vat": 0,
        "stampDuty": 0,
        "isDeleted": false,
        "otpVerified": true,
        "otpResendCount": 0,
        "createdAt": "2025-11-06T08:52:22.903Z",
        "updatedAt": "2025-11-24T08:59:20.395Z",
        "__v": 0,
        "debitMessage": "Approved or completed successfully",
        "debitResponsCode": 200,
        "debitSessionId": "090286251106085223546652615862",
        "otpId": "690c61ca8d3d86c9e8b3cad1",
        "providerResponse": {
            "bvn": "12345678901",
            "fullName": "John Doe",
            "firstName": "John",
            "middleName": "",
            "lastName": "Doe",
            "dateOfBirth": "14-02-1920",
            "phoneNumber1": "0812345678",
            "phoneNumber2": "0812345678",
            "gender": "Male",
            "enrollmentBank": "enrollmentBank",
            "enrollmentBranch": "enrollmentBranch",
            "email": "email",
            "lgaOfOrigin": "lgaOfOrigin",
            "lgaOfResidence": "lgaOfResidence",
            "maritalStatus": "Single",
            "nin": "",
            "nationality": "",
            "residentialAddress": "",
            "stateOfOrigin": "stateOfOrigin",
            "stateOfResidence": "",
            "title": "",
            "watchListed": "",
            "levelOfAccount": "",
            "registrationDate": null,
            "imageBase64": "/9j/4AAQSkZJRgABAgAAAQ"
        }
    }
}