Look up a Nigerian NIN or BVN
curl --request POST \
--url https://api-production.fossapay.com/api/v1/kyc/verifications \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: <x-idempotency-key>' \
--header 'x-api-key: <api-key>' \
--data '
{
"identityNumber": "<string>"
}
'import requests
url = "https://api-production.fossapay.com/api/v1/kyc/verifications"
payload = { "identityNumber": "<string>" }
headers = {
"X-Idempotency-Key": "<x-idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Idempotency-Key': '<x-idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({identityNumber: '<string>'})
};
fetch('https://api-production.fossapay.com/api/v1/kyc/verifications', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-production.fossapay.com/api/v1/kyc/verifications",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'identityNumber' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Idempotency-Key: <x-idempotency-key>",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-production.fossapay.com/api/v1/kyc/verifications"
payload := strings.NewReader("{\n \"identityNumber\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-production.fossapay.com/api/v1/kyc/verifications")
.header("X-Idempotency-Key", "<x-idempotency-key>")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"identityNumber\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-production.fossapay.com/api/v1/kyc/verifications")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"identityNumber\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"reference": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"method": "NIN",
"charged": true,
"feeAmount": "<string>",
"currency": "NGN",
"person": {
"identityNumber": "<string>",
"firstName": "<string>",
"middleName": "<string>",
"lastName": "<string>",
"dateOfBirth": "<string>",
"gender": "<string>",
"phoneNumber": "<string>",
"email": "<string>",
"address": "<string>"
}
}{
"status": "<string>",
"statusCode": 123,
"message": "<string>",
"error": "<string>",
"code": "<string>",
"errors": {}
}{
"status": "<string>",
"statusCode": 123,
"message": "<string>",
"error": "<string>",
"code": "<string>",
"errors": {}
}{
"status": "<string>",
"statusCode": 123,
"message": "<string>",
"error": "<string>",
"code": "<string>",
"errors": {}
}{
"status": "<string>",
"statusCode": 123,
"message": "<string>",
"error": "<string>",
"code": "<string>",
"errors": {}
}{
"status": "<string>",
"statusCode": 123,
"message": "<string>",
"error": "<string>",
"code": "<string>",
"errors": {}
}{
"status": "<string>",
"statusCode": 123,
"message": "<string>",
"error": "<string>",
"code": "<string>",
"errors": {}
}Identity Verification
Verify Identity
Look up a Nigerian NIN for ₦120 or BVN for ₦70 per attempt
POST
/
api
/
v1
/
kyc
/
verifications
Look up a Nigerian NIN or BVN
curl --request POST \
--url https://api-production.fossapay.com/api/v1/kyc/verifications \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: <x-idempotency-key>' \
--header 'x-api-key: <api-key>' \
--data '
{
"identityNumber": "<string>"
}
'import requests
url = "https://api-production.fossapay.com/api/v1/kyc/verifications"
payload = { "identityNumber": "<string>" }
headers = {
"X-Idempotency-Key": "<x-idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Idempotency-Key': '<x-idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({identityNumber: '<string>'})
};
fetch('https://api-production.fossapay.com/api/v1/kyc/verifications', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-production.fossapay.com/api/v1/kyc/verifications",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'identityNumber' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Idempotency-Key: <x-idempotency-key>",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-production.fossapay.com/api/v1/kyc/verifications"
payload := strings.NewReader("{\n \"identityNumber\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-production.fossapay.com/api/v1/kyc/verifications")
.header("X-Idempotency-Key", "<x-idempotency-key>")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"identityNumber\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-production.fossapay.com/api/v1/kyc/verifications")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"identityNumber\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"reference": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"method": "NIN",
"charged": true,
"feeAmount": "<string>",
"currency": "NGN",
"person": {
"identityNumber": "<string>",
"firstName": "<string>",
"middleName": "<string>",
"lastName": "<string>",
"dateOfBirth": "<string>",
"gender": "<string>",
"phoneNumber": "<string>",
"email": "<string>",
"address": "<string>"
}
}{
"status": "<string>",
"statusCode": 123,
"message": "<string>",
"error": "<string>",
"code": "<string>",
"errors": {}
}{
"status": "<string>",
"statusCode": 123,
"message": "<string>",
"error": "<string>",
"code": "<string>",
"errors": {}
}{
"status": "<string>",
"statusCode": 123,
"message": "<string>",
"error": "<string>",
"code": "<string>",
"errors": {}
}{
"status": "<string>",
"statusCode": 123,
"message": "<string>",
"error": "<string>",
"code": "<string>",
"errors": {}
}{
"status": "<string>",
"statusCode": 123,
"message": "<string>",
"error": "<string>",
"code": "<string>",
"errors": {}
}{
"status": "<string>",
"statusCode": 123,
"message": "<string>",
"error": "<string>",
"code": "<string>",
"errors": {}
}Retrieves the available person details for a Nigerian NIN or BVN. The endpoint does not compare a submitted name or DOB and does not make a verification decision. Each NIN provider attempt costs ₦120 and each BVN provider attempt costs ₦70, including attempts that return no person details.
Nigeria is selected automatically. Do not include
Both responses represent a charged lookup attempt. Your business decides how to handle the returned details or their absence.
See the Identity Verification Guide for pricing examples and integration steps.
Headers
string
required
An active production FossaPay API key with full permission. The associated business must have completed verification.
string
required
A unique key for this logical verification request, up to 255 characters. Retry with the same key and identical body to avoid an additional charge.
Body
string
required
NIN or BVN.string
required
The person’s 11-digit NIN or BVN. Preserve leading zeros.
country, names, date of birth, or consent in the request body.
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-bvn-v1" \
--header 'Content-Type: application/json' \
--data '{
"method": "BVN",
"identityNumber": "01234567890"
}'
Response
HTTP200 returns the result directly:
{
"reference": "11111111-1111-4111-8111-111111111111",
"method": "BVN",
"charged": true,
"feeAmount": "70.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 returns the identity number and the available person details. Optional fields are null when unavailable. The response does not include provider metadata or a verification decision. The reference is FossaPay’s identifier for the request.
When no usable person details are returned, the full response has the same shape with person: null:
{
"reference": "22222222-2222-4222-8222-222222222222",
"method": "BVN",
"charged": true,
"feeAmount": "70.00",
"currency": "NGN",
"person": null
}
Idempotency
- An identical completed request with the same key returns the original result and its original fee without another charge, even if the current price has changed.
- Reusing the key with a different request body returns
409. - A request still processing may return
409or503. Retry only with the same key and body. If it remains unresolved, contact support with the idempotency key and any returned reference. - If a request was rejected before verification and no charge was made, correct the issue and use a new key for the new request.
Errors
| HTTP status | Meaning |
|---|---|
400 | Missing or oversized idempotency key, unsupported method, invalid identity number, no active NGN master wallet, or insufficient available balance. |
401 | Missing, invalid, inactive, revoked, or non-production API key. |
403 | The merchant account is suspended or has not completed business verification. |
409 | The idempotency key was reused with different details, or the original request is still processing. |
422 | Request body failed field validation. |
503 | Verification is temporarily unavailable or a prior request needs reconciliation. Retry the same request with the same key when the outcome is unclear. |
Authorizations
Headers
Unique key for this verification request. Maximum 255 characters.
Required string length:
1 - 255Body
application/json
Response
Identity lookup attempt completed and charged
Available options:
NIN, BVN New NIN attempts cost 120.00 NGN and new BVN attempts cost 70.00 NGN. Idempotent replays retain the original fee, including earlier prices.
Allowed value:
"NGN"Show child attributes
Show child attributes

