Identity Verification Guide

Use Identity Verification when your business needs to retrieve the available details for a Nigerian National Identification Number (NIN) or Bank Verification Number (BVN). Send requests from your server with a live FossaPay API key. A NIN lookup costs ₦120 and a BVN lookup costs ₦70 per successful call. Production endpoint: POST https://api-production.fossapay.com/api/v1/kyc/verifications

This endpoint uses production access and can charge your business. Obtain any consent needed for your use case before submitting an identity number. Keep the API key and identity number out of browser code, URLs, analytics, and application logs.

Before you begin

Complete your FossaPay business verification and use an active production API key.
Have an active NGN master wallet with at least ₦120 for a NIN attempt or ₦70 for a BVN attempt.
Have the person’s 11-digit NIN or BVN.

How it works

Collect the identity number

Obtain the NIN or BVN and handle any consent records in your own system.

Send one verification request

Choose NIN or BVN and include a unique X-Idempotency-Key. Send the request from your backend.

Check the result

FossaPay checks that your business has enough NGN available, charges the ₦120 NIN or ₦70 BVN fee for the lookup attempt, and returns the available person details in person. Use those details to apply your own verification rules.

Handle a delayed response

If the request times out or returns a temporary error, retry the same request with the same idempotency key. A completed request returns its original result without another charge.

Example request

curl --request POST \
  --url https://api-production.fossapay.com/api/v1/kyc/verifications \
  --header "x-api-key: $FOSSAPAY_API_KEY" \
  --header "X-Idempotency-Key: verify-customer-10025-nin-v1" \
  --header 'Content-Type: application/json' \
  --data '{
    "method": "NIN",
    "identityNumber": "01234567890"
  }'

For a BVN lookup, change method to BVN and supply the person’s BVN as identityNumber. Keep the identity number as an 11-digit string so leading zeros are preserved.

Read the response

{
  "reference": "11111111-1111-4111-8111-111111111111",
  "method": "NIN",
  "charged": true,
  "feeAmount": "120.00",
  "currency": "NGN",
  "person": {
    "identityNumber": "01234567890",
    "firstName": "Ada",
    "middleName": "Ngozi",
    "lastName": "Okoro",
    "dateOfBirth": "1990-05-15",
    "gender": "female",
    "phoneNumber": "08012345678",
    "email": "ada@example.com",
    "address": "12 Example Street"
  }
}

person contains the submitted identity number and the available returned details. Optional details may be null when unavailable. If the lookup returns no usable details, person is null. The response does not decide whether the person meets your verification requirements. A completed attempt is charged the method-specific fee in either case. Retain reference for support and reconciliation.

Pricing and retries

Situation	Charge	What to do
A completed lookup returns person details	₦120 NIN / ₦70 BVN	Apply your own verification rules.
The request is rejected before lookup because it is invalid or the NGN balance is insufficient	₦0	Correct the request or fund your wallet.
The outcome is delayed or unclear	Do not assume	Retry the identical request with the same idempotency key.
The same completed request is replayed with the same idempotency key	₦0 additional	Use the returned original result.

An idempotent replay keeps the price charged when the original attempt was made, even if the current price has changed. Use a new idempotency key only when you intentionally want a new verification attempt. Reusing a key with different details returns 409.

See Verify identity for the complete request fields, response, and HTTP errors.

Getting Started

Core Concepts

Guides

AI Tools

Identity Verification Guide

Before you begin

How it works

Example request

Read the response

Pricing and retries

​Before you begin

​How it works

​Example request

​Read the response

​Pricing and retries

Before you begin

How it works

Example request

Read the response

Pricing and retries