Validate customers

Learn how to validate identity details for your users

Overview

You can verify the identity details provided by your users by calling Okra's validation endpoints. This guide explains how you can use Okra's customer validation endpoints with your users' BVN, NIN, or account numbers.

Using BVN

Okra recommends that you leverage the Identity API in this order to verify using BVN:

  1. Use the bvn-verify operation to verify customers and retrieve their identity details for the first time

This operation retrieves your customers’ KYC profile from their financial institutions using their Bank Verification Number.

  1. Check the response data from bvn-verify

You can utilize your customers’ identity details such as identity ids for verification and KYC purposes.

  1. Use the get identity operations to retrieve the identity profiles of already verified customers

For example, use your customers’ identity id with the get identity by id operation to retrieve their identity profile.

curl -X POST https://api.okra.ng/v2/products/kyc/bvn-verify
-H 'Content-Type: application/json'
-d '{
  "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
}'
{
    "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