BVN Verify OTP

Verify the OTP code received and returns the complete BVN data including the holder's personal information. This is the final step of the 3-step BVN verification Flow for Nigeria 🇳🇬.

Endpoint

POST /kyc/nga/bvn/verify

Authentication

Type	Location	Name
API Key	Header	x-api-key

Request body

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
sessionId	string	Yes	Session ID obtained from the initiation step.
otp	string	Yes	OTP code received by the user. 6 digits.

Request example

{
  "sessionId": "5f9b1a2c-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
  "otp": "123456"
}

Responses

200 Success

Response parameters

Parameter	Type	Description
serviceResultCode	integer	Code that indicates the overall result of the service execution. See Service Result Code
serviceTime	string	Processing time (milliseconds).
serviceResultLog	string	Descriptive field for the result of the service execution. Includes details when there is an error or exception in the module.
serviceTransactionId	string	Transaction identifier associated with the request processed by the API.
data	object	Object with the complete BVN data. See table below.

Response parameters — data

The object data is returned without mapping or normalization, preserving the original names, format, and capitalization of the fields.

Parameter	Type	Description
bvn	string	Bank Verification Number.
first_name	string	Holder's first name(s).
middle_name	string	Middle name.
last_name	string	Holder's last name(s).
dob	string	Date of birth (YYYY-MM-DD).
phone_number	string	Registered phone number.
phone_number_2	string	Secondary phone number. May be null.
email	string	Registered email address.
gender	string	Gender. Possible values: Male, Female
state_of_origin	string	State of origin.
lga_of_origin	string	LGA (Local Government Area) of origin.
lga_of_Residence	string	LGA (Local Government Area) of residence. The R capital letter is literal: the field is returned with that exact capitalization.
address	string	Registered address. May be null or may not be present depending on the BVN record.
marital_status	string	Marital status.
nin	string	National Identification Number associated with the BVN.
nationality	string	Nationality. May be null or may not be present depending on the BVN record.
registration_date	string	BVN registration date.
watch_listed	boolean	Indicates whether the person is on a watch list.
photoId	string	Holder's photograph encoded in Base64.

Service Result Code

The serviceResultCode indicates the overall result of the service execution:

serviceResultCode	Description	HTTP code
200	The service execution was successful, the module processed the request correctly.	200

Response example

{
  "serviceResultCode": 200,
  "serviceTime": "1500",
  "serviceResultLog": "Success",
  "serviceTransactionId": "996c790d-89d7-6c8g-c31c-7d1367ce77ef",
  "data": {
    "bvn": "12345678901",
    "first_name": "JOHN",
    "middle_name": "PAUL",
    "last_name": "DOE",
    "dob": "1990-01-15",
    "phone_number": "08012345678",
    "phone_number_2": null,
    "email": "[email protected]",
    "gender": "Male",
    "state_of_origin": "Lagos State",
    "lga_of_origin": "Yaba",
    "lga_of_Residence": "Yaba",
    "address": "12 BEN STREET LAGOS",
    "marital_status": "single",
    "nin": "12345678901",
    "nationality": "Nigeria",
    "registration_date": "2015-06-20",
    "watch_listed": false,
    "photoId": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
  }
}

400 Bad Request

Error returned with the service envelope (serviceResultCode reflects the HTTP response code):

{
  "serviceResultCode": 400,
  "serviceResultLog": "Sorry, lookup failed. Please check the details and try again",
  "serviceTime": "151",
  "serviceTransactionId": "08ac9699-dc9e-4cdc-81d7-264f71838309"
}

502 Bad Gateway

Returned when the service is temporarily unavailable or its response could not be interpreted. The body uses the service envelope with serviceResultCode: 500:

{
  "serviceResultCode": 500,
  "serviceResultLog": "Service temporarily unavailable. Please try again later",
  "serviceTime": "3000",
  "serviceTransactionId": "38de2932-0f2h-7gff-14g0-597h04161632"
}

504 Gateway Timeout

Timeout error, returned with the service envelope:

{
  "serviceResultCode": 504,
  "serviceResultLog": "Request timeout. Please try again",
  "serviceTime": "30000",
  "serviceTransactionId": "48ef3043-1g3i-8hgg-25h1-608i15272743"
}

Authentication errors (401/403) are rejected by the gateway before reaching the service and do not use the envelope serviceResultCode. Platform validation errors use the format application/problem+json. See Error handling for details on the three response forms.