Skip to content
HitchPay API Docs

Simulator

Simulate NG Identity

Test the full BVN/NIN verification request/response without spending a real lookup or touching your wallet. Available only in the sandbox/development environment.

Use these endpoints to

  • Build and test your integration before it can perform real lookups
  • Simulate a "not found" response without needing a real invalid ID

Endpoints

Method Path Mirrors
POST /v1/sandbox/verify-bvn Verify BVN
POST /v1/sandbox/verify-nin Verify NIN

Same request body as the live endpoints. Returns a canned details record with fee: 0 - nothing is charged.

Body parameters

Field Type Required Description
id string Yes The 11-digit BVN or NIN
reference string No Idempotency key, same behavior as the live endpoints

Test inputs

Test input Result
Any valid 11-digit ID verified: true with mock details
An ID ending in 0000 NOT_FOUND — simulates no record
Test BVN - 22222222222
Test NIN - 70123456789

Code Samples

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

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

$ch = curl_init();

curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/sandbox/verify-bvn",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode(["id" => "22345678901"]),
  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/sandbox/verify-bvn"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {"id": "22345678901"}

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

Response

{
  "status": "success",
  "message": "BVN verified successfully.",
  "data": {
    "reference": "HTCHV1A2B3C4D5",
    "merchant_reference": null,
    "type": "bvn",
    "verified": true,
    "fee": 0,
    "currency": "NGN",
    "balance": 5000,
    "details": {
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1990-05-12"
    }
  }
}

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