Wallet & Identity

Identity Verification (KYC)

Verify end-user identities in real time against Nigerian identity databases (NIN and BVN) to satisfy compliance, AML, and onboarding requirements.

Base Path/api/v1/partner/kyc

Authx-api-key (+ x-signature on verify)

Supported ID Typesbvn · nin

Rate limit30 requests / 60s (failure circuit breaker)

Verify Customer Identity

Perform an identity verification query by passing the customer's BVN or NIN along with their legal name and date of birth:

Verify customer BVN or NIN

POST /partner/kyc/verify

Signature required

Field	Type	Required	Description
identificationType	string	required	`bvn` or `nin` (case-insensitive)
value	string	required	11-digit BVN or NIN number
firstname	string	required	Claimed first name
lastname	string	required	Claimed last name
middlename	string	optional	Claimed middle name (if available)
dateOfBirth	string	required	Format: `YYYY-MM-DD`
phoneNumber	string	optional	Customer phone number for cross-matching
partnerReference	string	optional	Unique reference for tracking the verification event

cURL

Node.js

curl -X POST https://api.billpadi.com/api/v1/partner/kyc/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "identificationType": "bvn",
    "value": "22198765432",
    "firstname": "Chinedu",
    "lastname": "Okeke",
    "dateOfBirth": "1994-08-22",
    "phoneNumber": "+2348031234567",
    "partnerReference": "KYC-USER-10294"
  }'

const res = await partnerClient.post("/kyc/verify", {
  identificationType: "bvn",
  value: "22198765432",
  firstname: "Chinedu",
  lastname: "Okeke",
  dateOfBirth: "1994-08-22",
  partnerReference: "KYC-USER-10294"
});

Example response — 200 OK

{
  "success": true,
  "message": "Identity verified successfully",
  "data": {
    "verified": true,
    "confidence": 100,
    "reference": "KYC_1720603200000_1A2B",
    "partnerReference": "KYC-USER-10294",
    "matchDetails": {
      "firstname": true,
      "lastname": true,
      "dateOfBirth": true
    },
    "fee": 150
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/kyc/verify"
}

Lookup Verification Transaction

Get KYC verification status by reference

GET /partner/kyc/transactions/:reference

API Key only

List KYC Verification Transactions

Retrieve paginated verification records with optional status filtering:

List verification audit logs

GET /partner/kyc/transactions

API Key only

Param	Type	Default	Description
page	integer	`1`	Page number
limit	integer	`20`	Results per page
status	string	—	Filter by status: `success` or `failed`

cURL

curl "https://api.billpadi.com/api/v1/partner/kyc/transactions?page=1&limit=20" \
  -H "x-api-key: $API_KEY"

Example response — 200 OK

{
  "success": true,
  "message": "Transactions retrieved",
  "data": [
    {
      "reference": "KYC_1720603200000_1A2B",
      "partnerReference": "KYC-USER-10294",
      "identificationType": "bvn",
      "status": "success",
      "verified": true,
      "fee": 150,
      "createdAt": "2026-07-10T09:20:03.000Z"
    }
  ],
  "pagination": {
    "total": 48,
    "page": 1,
    "limit": 20,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/kyc/transactions"
}

← PreviousWithdrawals & Payouts Next →Airtime