Validate customers

Learn how to validate identification details for your customers

Overview

Verifying the identifications details provided by your customers is done by calling the customer's validation endpoints.
Depending on the details provided by your customer, you can verify based on their BVN details, NIN details, or account number, by sending a POST request to any of the customer validation endpoints.

Using BVN

With the BVN-verify endpoint, you can look up customer information using their Bank Verification Number(BVN), by requesting them to provide their BVN.
There are two ways you can do a BVN Check / Retrieval, either via our Widget or directly via our API.
You can use the response gotten from BVN to obtain a KYC profile of your customer and verify them.

curl -X POST https://api.okra.ng/v2/products/kyc/bvn-verify
-H 'Content-Type: application/json'
-d '{
  "testing" : boolean, // optional if testing
  "success": boolean, //options if testing 
  "currency" : "NGN",
  "bvn" : "String"
}'
{
    "status": "success",
    "message": "Identity succesfully retrieved",
    "data": {
        "identity": {
            "fullname": "GAVIN BELSON",
            "id": "5da635898ytghi9876tgh",
            "bvn": "12331106253",
            "score": "0",
            "env": "production",
            "created_at": "2019-12-14T13:46:53.415Z",
            "last_updated": "2021-01-26T10:14:56.300Z",
            "aliases": [],
            "customer": {
                "_id": "5da635898ytghi9876tgh",
                "name": "GAVIN BELSON"
            },
            "dob": "1979-09-27",
            "gender": "M",
            "middlename": "MIDDLENAME",
            "firstname": "GAVIN",
            "lastname": "BELSON",
            "phone": [
                "2347088793567"
            ],
            "email": [],
            "address": [
                "4 AKANNI BASHORUN,LEKKI  LAGOS"
            ],
            "verified": true,
            "photo_id": [{..photo data..}
            ],
            "status": "failed"
        },
        "customer": "5da635898ytghi9876tgh",
        "account": "5da635898ytghi9876tgh",
        ........
        },
        ........
    }
}

Using NUBAN

What if you don't want to request your user for their BVN? you can as well request their account number via proper GDPR / NDPR guidelines, and with that, you can verify a customer's identity using only their NUBAN, by sending a POST request to the nuban-verify endpoint.

curl -X POST https://api.okra.ng/v2/products/kyc/nuban-verify
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{
    "nuban":  ACCOUNT NUMBER,
    "bank": BANK ID,
    "testing": true/false, //TRUE if for testing purposes only
    "success: true/false // ONLY send with testing "true"
}'
{
    "status": "success",
    "message": "Identity succesfully retrieved",
    "data": {
        "identity": {
            "fullname": "GAVIN BELSON",
            "id": "5da6358130a943486f288d9d",
            "bvn": "12331106253",
            "score": "0",
            "env": "production",
            "created_at": "2019-12-14T13:46:53.415Z",
            "last_updated": "2021-01-26T10:14:56.300Z",
            "aliases": [],
            "customer": {
                "_id": "5da6358130a943486f288d9d",
                "name": "GAVIN BELSON"
            },
            "dob": "1979-09-27",
            "gender": "M",
            "middlename": "MIDDLENAME",
            "firstname": "GAVIN",
            "lastname": "BELSON",
            "phone": [
                "2347088793567"
            ],
            "email": [],
            "address": [
                "4 AKANNI BASHORUN,LEKKI  LAGOS"
            ],
            "verified": true,
            "photo_id": [{..photo data..}
            ],
            "status": "failed"
        },
        "customer": "5da6358130a943486f288d9d",
        "account": "5da6358130a943486f288d9d",
        "receipt": {
            "status": true,
            "msg": "Receipt has been successfully created",
            "data": {
                "receipt": {
                    "adjustment": {
                        "receipts": []
                    },
                    "breakdown": {
                        "discount": 0,
                        "billable_products": []
                    },
                    "billingStatus": true,
                    "adjusted": null,
                    "adjusted_receipt": false,
                    "adjusted_type": null,
                    "method": "wallet",
                    "charge": 250,
                    "wallet_balance": 993329.25,
                    "addons": [],
                    "_id": "5da6358130a943486f288d9d",
                    "owner": "5da6358130a943486f288d9d",
                    "type": "nuban-verify",
                    "currency": "NGN",
                    "plan": "payg",
                    "plan_type": "5da6358130a943486f288d9d",
                    "created_at": "2021-01-26T10:15:35.534Z",
                    "last_updated": "2021-01-26T10:15:35.534Z",
                    "__v": 0
                }
            }
        },
        "record": {
            "usedProduct": {
                "periodic-transactions": {
                    "status": false,
                    "number": 0
                },
                "guarantors": {
                    "status": false,
                    "number": 0
                },
                "directors": {
                    "status": false,
                    "number": 0
                },
                "auth": false,
                "balance": false,
                "accounts": false,
                "transactions": false,
                "income": false,
                "identity": true,
                "payment": false,
                "direct-debit": false
            },
            "status": {
                "process": {
                    "running": false,
                    "completed": true
                }
            },
            "retry": {
                "status": false
            },
            "fixed": false,
            "products": [
                "auth",
                "identity",
                "balance",
                "income",
                "transactions",
                "guarantors",
                "periodic-transactions",
                "periodic-balance"
            ],
            "billable_products": [
                "identity"
            ],
            "source": "api",
            "manual": true,
            "limit": 3,
            "connected_account": [
                "5da6358130a943486f288d9d"
            ],
            "account": [
                "5da6358130a943486f288d9d"
            ],
            "currency": "NGN",
            "adjusted": null,
            "projects": [],
            "_id": "5da6358130a943486f288d9d",
            "connectionId": "fjbc7li1ndr",
            "owner": "5da6358130a943486f288d9d",
            "bank": "5da6358130a943486f288d9d",
            "app_v": 2,
            "env": "production",
            "created_at": "2021-01-26T10:15:30.078Z",
            "last_updated": "2021-01-26T10:15:35.837Z",
            "__v": 0,
            "customer": "5da6358130a943486f288d9d"
        }
    }
}

Name Check

Depending on what you're working on, sometimes you might need to verify only the Full-name provided by a user, as opposed to what is in the BVN data.
For such a scenario the v2/products/kyc/name-verify endpoint will come in very handy.
This endpoint can be used in two ways.
The payload can either be the bvn of the user which will return the user's Full-name or the account number of the user, which will also return the user's Full-name.

curl -X POST https://api.okra.ng/v2/products/kyc/name-verify
-H 'Content-Type: application/json'
-d '{
  "bvn" : "1234567890"
}'
curl -X POST https://api.okra.ng/v2/products/kyc/name-verify
-H 'Content-Type: application/json'
-d '{
  "nuban" : "1234567890", "bank": "BANK_ID"
}'
{
    "status": "success",
    "message": "Identity succesfully retrieved",
    "data": {
        "identity": {
            "fullname": "GAVIN BELSON BOLUWATIFE",
              ........
        },
    }
}

Check out the Identity API Reference


Did this page help you?