KYC

Verify business and individual identities through BVN lookups and document uploads.

---

KYC Lookup

GET /kyc/lookup

Look up identity information using BVN or other supported identifiers.

Headers

Field	Value
Authorization	Bearer PAYSCRIBE_API_KEY

Query Parameters

Field	Type	Required	Description
type	string	Yes	Identifier type: bvn, nin, or driver_license.
value	string	Yes	The identifier value to look up. For bvn, must be an 11-digit BVN number.

Request

cURL

curl -X GET "https://sandbox.payscribe.ng/api/v1/kyc/lookup?type=bvn&value=12345678901" \
  -H "Authorization: Bearer $PAYSCRIBE_API_KEY"

Node.js

const response = await fetch('https://sandbox.payscribe.ng/api/v1/kyc/lookup?type=bvn&value=12345678901', {
  method: 'GET',
  headers: {Authorization: `Bearer ${process.env.PAYSCRIBE_API_KEY}`},
});

const result = await response.json().catch(() => null);
if (!response.ok) throw new Error(`Payscribe request failed: ${response.status}`);
console.log(result);

Python

import os
import requests

response = requests.get(
    'https://sandbox.payscribe.ng/api/v1/kyc/lookup?type=bvn&value=12345678901',
    headers={'Authorization': f"Bearer {os.environ['PAYSCRIBE_API_KEY']}"},
    timeout=20,
)
response.raise_for_status()
print(response.json())

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  var body io.Reader
  request, err := http.NewRequest(http.MethodGet, "https://sandbox.payscribe.ng/api/v1/kyc/lookup?type=bvn&value=12345678901", body)
  if err != nil { panic(err) }
  request.Header.Set("Authorization", "Bearer "+os.Getenv("PAYSCRIBE_API_KEY"))

  response, err := http.DefaultClient.Do(request)
  if err != nil { panic(err) }
  defer response.Body.Close()
  responseBody, _ := io.ReadAll(response.Body)
  if response.StatusCode < 200 || response.StatusCode > 299 { panic(fmt.Sprintf("Payscribe request failed: %s", response.Status)) }
  fmt.Println(string(responseBody))
}

Response

Status: 200 OK

{
  "status": true,
  "description": "Lookup successful.!",
  "message": {
    "details": {
      "first_name": "John",
      "last_name": "Doe",
      "middle_name": "Adetokunbo",
      "gender": "male",
      "phone_number": "0910088228",
      "expiry_date": null,
      "dob": "2026-09-17 10:15:00",
      "photo": "base64",
      "transaction_status": "success",
      "amount": "35.00",
      "total_charge": "5.00",
      "trans_id": "e5c9b0b0-6b1a-4b3e-9c9a-7b1a6b1a4b3e",
      "type": "bvn",
      "value": "12345678901",
      "datetime": "2026-09-17 10:15:00",
      "score": null,
      "blacklist": false
    }
  },
  "status_code": 200
}

middle_name, expiry_date, and photo are only populated for identifier types that return them (nin/driver_license); a bvn lookup may omit expiry_date. amount is what was charged to the business wallet for this lookup (BVN costs less than NIN/driver's license); total_charge mirrors it. score is currently always null and blacklist is always false — reserved fields, not yet populated.