BVN Resolution

​

Overview

The BVN resolution endpoint allows you to verify customer identity using their Bank Verification Number (BVN) as part of KYC requirements in Nigeria.

​

Endpoint

POST /payment-methods/resolve-bvn

​

Request Parameters

​

Example Request

curl -X POST "https://api.spendjuice.com/payment-methods/resolve-bvn" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "bvn": "22222222222"
}'

​

Response Format

​

Success Response

{
  "data": {
    "date_of_birth": "02-Feb-87",
    "first_name": "Aishatu",
    "middle_name": "",
    "mobile_number": "08034903346",
    "surname": "Sadiq"
  }
}

​

Error Responses

{
  "error": {
    "code": "invalid_bvn",
    "message": "The provided BVN is invalid",
    "details": {
      "bvn": ["Must be 11 digits"]
    }
  }
}

{
  "error": {
    "code": "bvn_not_found",
    "message": "BVN not found in the database"
  }
}

{
  "error": {
    "code": "service_error", 
    "message": "Unable to resolve BVN"
  }
}

​

Implementation Guide

1. Consent Collection

   • Display clear consent message

   • Document consent in your records

   • Include in terms of service

2. Data Handling

   • Never store raw BVN numbers

   • Encrypt any stored verification results

   • Implement proper access controls

3. Error Handling

   • Show user-friendly error messages

   • Implement exponential backoff for retries

   • Log resolution failures for debugging