Identity

Verify BVN

Look up a Nigerian Bank Verification Number and get the identity record back directly in the response.

POST /v1/identity/bvn

Use this endpoint to

Resolve a BVN to a name, date of birth, and other identity details
Confirm a customer's identity without creating a stored customer profile
Safely retry a lookup without double-charging, using reference

Request

Body parameters

Field	Type	Required	Description
`id`	string	Yes	The 11-digit BVN. `bvn` / `number` are also accepted as the field name
`reference`	string	No	Idempotency key — a repeat call with the same `reference` returns the earlier result without charging again

Code Samples

const response = await fetch("https://sandbox.hitchpay.ng/v1/identity/bvn", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    id: "22345678901",
    reference: "order-8842"
  })
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init();

curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/identity/bvn",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "id" => "22345678901",
    "reference" => "order-8842"
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Content-Type: application/json"
  ]
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

import requests

url = "https://sandbox.hitchpay.ng/v1/identity/bvn"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "id": "22345678901",
    "reference": "order-8842"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

{
  "status": "success",
  "message": "BVN verified successfully.",
  "data": {
    "reference": "HTCHV1A2B3C4D5",
    "merchant_reference": "order-8842",
    "type": "bvn",
    "verified": true,
    "fee": 50,
    "currency": "NGN",
    "balance": 4950,
    "details": {
      "first_name": "John",
      "last_name": "Doe",
      "middle_name": "…",
      "date_of_birth": "1990-05-12",
      "phone_number1": "080…",
      "gender": "Male",
      "image": "<base64 photo>"
    }
  }
}

Fields

Field	Type	Description
`reference`	string	Our transaction id for this lookup
`merchant_reference`	string	Echoes the `reference` you sent, or `null` if you didn't send one
`type`	string	`bvn`
`verified`	boolean	Whether a record was found — `true` means you were charged
`fee`	number	Amount charged for this lookup
`currency`	string	`NGN`
`balance`	number	Your wallet balance after this lookup
`details`	object	The provider's identity record — field set depends on the provider payload for this ID

Errors

Code	HTTP	Meaning	Charged?
`INVALID_REQUEST`	400	Missing `id`, or not 11 digits	No
`INSUFFICIENT_BALANCE`	400	Wallet can't cover the per-call fee	No
`NOT_FOUND`	404	No identity record for the supplied ID	No — auto-refunded if a debit occurred
`PROVIDER_ERROR`	502	The verification provider was unreachable	No — auto-refunded
`SERVICE_UNAVAILABLE`	503	This product isn't priced/enabled right now	No
`DEBIT_FAILED`	400	Wallet debit could not be completed	No
`REQUEST_FAILED`	500	Unexpected error; any debit is reversed	No

Questions? Email [email protected]. Also on GitBook.