BVN Initiate

Initiates the verification process BVN (Bank Verification Number) for Nigeria and returns the available verification methods (phone, phone_1, email, alternate_phone) for sending the OTP.

Endpoint

POST /kyc/nga/bvn/initiate

Authentication

Type	Location	Name
API Key	Header	x-api-key

Request body

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
bvn	string	Yes	Bank Verification Number of 11 digits.
scope	string	Yes	Query scope. Possible values: identity, bank_accounts

Request example

{
  "bvn": "12345678901",
  "scope": "identity"
}

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 of 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 session data and available methods. See table below.

Response parameters — data

Parameter	Type	Description
session_id	string	Session ID for the following verification steps.
methods	array	Available methods for OTP verification. See table below.

Response parameters — data.methods[]

Parameter	Type	Description
method	string	Verification method type. Possible values: phone, phone_1, email, alternate_phone
hint	string	Full phrase indicating where the code will be sent, and includes the phone or email address partially masked. The exact text may vary.

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": "1200",
  "serviceResultLog": "Success",
  "serviceTransactionId": "796a580b-67b5-4a6e-a19a-5b9145ad55cd",
  "data": {
    "session_id": "5f9b1a2c-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
    "methods": [
      {
        "method": "phone",
        "hint": "Sms with a verification code will be sent to phone 0803***3843"
      },
      {
        "method": "email",
        "hint": "An email with a verification code will be sent to j***[email protected]"
      },
      {
        "method": "alternate_phone",
        "hint": "Sms with a verification code will be sent to your alternate phone number"
      }
    ]
  }
}

400 Bad Request

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

{
  "serviceResultCode": 400,
  "serviceResultLog": "Invalid BVN format. Please check the details and try again",
  "serviceTime": "120", 
  "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 timeout, 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 formats.