Skip to Content
Parent Loans APIBVN Verification

BVN Verification

Parents must verify their BVN before credit assessment or loan submission. Skip this entirely if login/SSO already returned isBvnVerified: true.

Use the same sessionId from step 1 in steps 2 and 3. Use the same bvn in steps 1 and 3.

Non-production testing: when the API isn’t running in production mode, Initiate still returns a real session; Choose OTP method doesn’t send a real SMS; Confirm OTP accepts OTP 000000 only.

BVN 1: Initiate

POST /api/auth/bvn/initiate

Starts the BVN lookup. Returns a sessionId and the available OTP delivery methods (each with a method and a hint). Save sessionId for steps 2 and 3.

Headers

HeaderValue
Acceptapplication/json
AuthorizationBearer {parentAccessToken}
Content-Typeapplication/json

Request body

FieldDescription
bvnThe parent’s 11-digit BVN.
{
  "bvn": "22222222222"
}

Response 200

{
  "success": true,
  "message": "BVN Lookup successfully initiated.",
  "data": {
    "sessionId": "7V9JFeOKlO6hV1MQxz9g",
    "methods": [
      {
        "method": "phone",
        "hint": "Sms with a verification code will be sent to phone 0810***0397"
      },
      {
        "method": "alternate_phone",
        "hint": "Sms with a verification code will be sent to your alternate phone number"
      }
    ]
  },
  "errors": [],
  "statusCode": 200
}
FieldDescription
sessionIdCarry this into BVN 2 and BVN 3.
methodsWhere an OTP can be sent, each has a method key (phone, alternate_phone, …) and a human-readable hint.

Try it

POST/api/auth/bvn/initiate

BVN 2: Choose OTP method

POST /api/auth/bvn/verify-method

Sends the OTP via the chosen method (from step 1’s methods list, phone or alternate_phone).

Headers

HeaderValue
Acceptapplication/json
AuthorizationBearer {parentAccessToken}
Content-Typeapplication/json

Request body

FieldDescription
sessionIdFrom BVN 1: Initiate.
methodphone or alternate_phone, from step 1’s methods.
phoneNumberOptional.
{
  "sessionId": "REPLACE_FROM_INITIATE",
  "method": "phone",
  "phoneNumber": null
}

Response 200

{
  "success": true,
  "message": "OTP sent successfully.",
  "data": {
    "message": "OTP sent successfully."
  },
  "errors": [],
  "statusCode": 200
}

Try it

POST/api/auth/bvn/verify-method

BVN 3: Confirm OTP

POST /api/auth/bvn/confirm

Confirms the OTP and persists the BVN on the parent’s account. Use the same bvn as BVN 1: Initiate.

Non-production: use OTP 000000.

Headers

HeaderValue
Acceptapplication/json
AuthorizationBearer {parentAccessToken}
Content-Typeapplication/json

Request body

FieldDescription
sessionIdFrom BVN 1: Initiate.
otpThe code delivered in step 2.
bvnSame BVN as step 1.
bvnPhoneNumberOptional.
{
  "sessionId": "REPLACE_FROM_INITIATE",
  "otp": "000000",
  "bvn": "22222222222",
  "bvnPhoneNumber": "08012345678"
}

Response 200

{
  "success": true,
  "message": "BVN verified successfully.",
  "data": {
    "message": "BVN verified successfully."
  },
  "errors": [],
  "statusCode": 200
}

Try it

POST/api/auth/bvn/confirm
OverviewCredit Assessment