Identity

Verify NIN

Look up a Nigerian National Identity Number and get the identity record back directly in the response.

POST /v1/identity/nin

Use this endpoint to

Resolve a NIN 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 NIN. `nin` / `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/nin", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    id: "12345678901"
  })
});

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

<?php

$ch = curl_init();

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

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

Response

{
  "status": "success",
  "message": "NIN verified successfully.",
  "data": {
    "reference": "HTCHV9Z8Y7X6W5",
    "merchant_reference": null,
    "type": "nin",
    "verified": true,
    "fee": 40,
    "currency": "NGN",
    "balance": 4910,
    "details": {
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1990-05-12"
    }
  }
}

Fields

Field	Type	Description
`reference`	string	Our transaction id for this lookup
`merchant_reference`	string \| null	Echoes the `reference` you sent, or `null` if you didn't send one
`type`	string	`nin`
`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.