Identity

The Most Complete KYC/B (Know Your Customer or Business) Guide

Identity verification is vital when authenticating a user. We combine identity validation with ownership to reduce risk and fraud. Without the ability to digitally validate an end-user’s identity in real-time, consumers may be forced to manually upload and email sensitive information or even worse, submit a paper application.

📘

Need to verify customers against their biometric data?

Significantly reduce the possibility of fraud by confirming the person using your product is the account owner at the validated bank. Try Selfie Verification now.

These methods are less secure and less efficient than Okra’s automated and real-time alternative. Any user with online or mobile banking can validate ownership of their financial data, allowing you to safely unlock your services. Once a user connects, we can automatically retrieve BVN, biometric photo, and a full KYC profile — you’ll never ask for BVN again.

Read more about Identity @ get.okra.ng/identity-deck

Overview

Okra Identity product helps you verify users' identities by accessing the information on file with their financial institution and retrieve a full KYC profile for an individual or corporate entity across all banks in Nigeria. Using Identity, you can access a user's phone number, email address, mailing address, many more. This can be used for prefilling account information, as well as for verifying with a trusted source that information they provided about themselves is correct. Fraud reduction and complementing of Know Your Customer (KYC) compliance are common applications for Identity.

Use OkraJS to instantly authenticate your customer's account and retrieve a full identity profile in real-time:

  • Validated BVN or RC Number
  • Validated Company Registration and Tax Details (corporate entities only)
  • BVN Identity Photo
  • DTI (Debt-to-Income score)
  • Mother’s Maiden Name*
  • Full Name or Company Name
  • Alias(es)
  • Gender*
  • Date of Birth
  • Email Address(es)
  • Addresses
  • Phone number(s)
  • Photo ID(s)*

Depending on the use case of your product, you may want to retrieve a full KYC profile from their bank, verify the identity of all users, or only some. For example, you might want to verify the identity of any user on your platform requesting a loan, or you might only validate users who you have identified as being underaged, supposing your platform require adults.

Add Identity to your app

In this guide, we'll walk through from scratch, how to use the Identity suites of APIs to retrieve users' data.
If you're familiar with using Okra and already have Okra setup on your machine, you can skip to Identity API, otherwise, carefully follow the next section.

Okra API Keys

If you're new to Okra, you'll need to create an Okra developer account.
After creating your account, you'll need to login.
To find your API keys, navigate to the Settings menu on the Okra developer dashboard.
To better understand how Okra API keys work, check this tutorial

Identity API

Before diving deep into the tutorial, it's important to note that Okra Identity API has the following endpoints;
☑️ BVN Retrieval
☑️ NUBAN Retrieval
☑️ RC/TIN KYB Retrieval
☑️ NIN Retrieval
In this guide, you'll learn how you can add any of these endpoints to your app.

BVN Verification / Retrieval

With this 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.

To simply put, the BVN endpoint allows you to verify that an account number, Fullname of a user matches their BVN.

Run a BVN check on any of your customer's

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"
}'
const axios = require('axios');
const qs = require('qs');

const secret_key = 'Your_Secret_KEY'; //add the secret key gotten from your dashboard
const bvnData = qs.stringify({
  "bvn": "user_BVN", 
});

const bvnUrl = 'https://api.okra.ng/v2/products/kyc/bvn-verify';

//retreive identity details
exports.bvnCheck = async (req, res) => {
    try {
        const response = await axios({
            url: bvnUrl,
            method: "post",
      headers: { 
        'Authorization': `Bearer ${secret_key}`,
        'Content-Type': 'application/x-www-form-urlencoded', 
      },
      data : bvnData
        });
        res.status(200).json(response.data);
    } catch (err) {
        res.status(500).json({ message: err });
    }
}
{
    "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"
        }
    }
}

Test it out live in our reference.

NUBAN Identity Retrieval

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

Fetch Identity by NUBAN

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"
}'
const axios = require('axios');
const qs = require('qs');

const secret_key = 'Your_Secret_KEY'; //add the secret key gotten from your dashboard
const nubanData = qs.stringify({
  "nuban": "user_Nuban",
});

const nubanUrl = 'https://api.okra.ng/v2/products/kyc/nuban-verify';

//retreive identity details
exports.nubanCheck = async (req, res) => {
    try {
        const response = await axios({
            url: nubanUrl,
            method: "post",
      headers: { 
        'Authorization': `Bearer ${secret_key}`,
        'Content-Type': 'application/x-www-form-urlencoded', 
      },
      data : nubanData
        });
        res.status(200).json(response.data);
    } catch (err) {
        res.status(500).json({ message: err });
    }
}
{
    "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"
        }
    }
}

You can find a list of Bank ID's here

RC/TIN KYB Retrieval

Verify any business in Nigeria using only their RC Number or RC Number and TIN

Coming soon to 🇰🇪Kenya and 🇿🇦South Africa

RC & TIN Verification

curl -X POST https://api.okra.ng/v2/products/kyc/rc-tin-verify
-H 'Content-Type: application/json'
-d '{
  "currency" : String,
  "rc_number" : String,
  "company_name" : String,
  "tin_number" : "String
}'
{
    "status": "success",
    "message": "Company RC & TIN successfully verified!",
    "data": {
        "rc_info": {
            "details": {
                "rc_no": "String",
                "company_name": "String",
                "address": "String",
                "date_reg": "String (YYYY-MM-DD)"
            },
            "status": "String (success || fail)",
            "message": "String"
        },
        "tin_info": {
            "status": "String (success || fail)",
            "message": "String",
            "details": {
                "tax_no": "String",
                "tax_payer_name": "String",
                "tax_payer_phone": "String",
                "tax_payer_email": "String",
                "tax_authority": "String",
                "tax_authority_phone": "String",
                "tax_authority_email": "String"
            }
        }
    }
}

RC Verification

curl -X POST https://api.okra.ng/v2/products/kyc/rc-verify
-H 'Content-Type: application/json'
-d ' {
    rc_number, //required
    company_name, // required
    success, //optional boolean (for testing)
    testing,//option boolean (for testing)
}'
{
    "status": "String (success || fail)",
    "message": "String",
    "data": {
        "status": boolean,
        "message": "String",
        "details": {
            "rc_no": "String",
            "company_name": "String",
            "address": "String",
            "date_reg": "String"
        }
    }
}

TIN Verification

l -X POST https://api.okra.ng/v2/products/kyc/tin-verify
-H 'Content-Type: application/json'
-d '{
  {
    "tax_no": "",
    "tax_payer_name": "",
    "tax_payer_phone": "",
    "tax_payer_email": "",
    "tax_authority": "",
    "tax_authority_phone": "",
    "tax_authority_email": " ",
    "currency" : "String",
    "tin_number" : "String"// required,
    "company_name", "String"// required,
    "dob" : "String (YYYY-MM-DD)",
  }
}'
{
    "status": "String (success || fail)",
    "message": "Company TIN Verified",
    "data": {
        "status": boolean,
        "message": "String",
        "details": {
            "tax_no": "String",
            "tax_payer_name": "String",
            "tax_payer_phone": "String",
            "tax_payer_email": "String",
            "tax_authority": "String",
            "tax_authority_phone": "String",
            "tax_authority_email": "String"
        }
    }
}

Test it out live in our reference.

NIN Retrieval

Verifying a customer using their NIN is simple. You can do a NIN Check / Retrieval either do via our Widget or directly via our API which will allow the customer to give you permission. You can use the resulting NIN to obtain the KYC profile of your customer and verify them.

Run a NIN check on any of your customer's

Run a quick check on any of your customers to verify their identity.

curl -X POST https://api.okra.ng/v2/products/kyc/nin-verify
-H 'Content-Type: application/json'
-d '{
  "testing" : boolean, // optional if testing
  "success": boolean, //options if testing 
  "currency" : "NGN",
  "nin" : "String"
}'
"tin_info": {
            "status": "String (success || fail)",
            "message": "String",
            "details": {
                "tax_no": "String",
                "tax_payer_name": "String",
                "tax_payer_phone": "String",
                "tax_payer_email": "String",
                "tax_authority": "String",
                "tax_authority_phone": "String",
                "tax_authority_email": "String"
            }
        }

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",
              ........
        },
    }
}

🚀Now that you understand what Identity is, check out API Reference to test the Identity API in real-time.


Did this page help you?