Mono Prove Integration Guide

Overview

This guide will put you through the necessary steps to take when trying to integrate Mono Prove into your software solution via API. This is made possible via a generated URL that can be sent to users for them to complete the process without a need for setting up SDKs.

Prerequisites

To get started, you need to:

• Sign up on the Partner Dashboard and complete KYB.
• Create a prove app and retrieve your Secret key.
• Configure a webhook URL in your dashboard to receive event notifications (you can use webhook.site for testing).

Re: Sandbox/Test Enviroment

• Kindly note that to test Prove in sandbox you simply need to pass your test keys in the headers of your request. You can find the test keys on your dashboard as shown by this guide.

• We also send test webhooks in sandbox to simplify your integration experience.

• The credentials passed for testing Prove in sandbox are random credentials.

Integration Guide

With the above prerequisite steps already taken, please note that there are three stages for completing the integration process:

Step 1: Initiate Prove Session

Make an API call to the Initiate Prove API endpoint. The API response will provide the necessary session initiation data. This data will contain either a mono_url for browser-based flows, or a request id for SDK integrations.

Step 2: User Session Access Setup

There are two ways to access this, namely:

a. SDK Integration: Instantiate the Prove web or mobile SDK widget using the provided request ID.

b. Prove Link: Direct the user to the provided mono_url in their web browser. Optionally the user may receive an email containing the same link.

Step 3: Identity Verification Onboarding:

The user will complete the identity verification process within the widget, which may include providing personal details, uploading/scanning documents, facial recognition, and granting necessary permissions.

Step 1: Initiate Prove Session

Initiate a call to the Prove API endpoint as shown below, providing key parameters such as customer information, KYC level, and tier type etc, which returns a response that will include the necessary initiation data, providing either mono_url for browser-based completion or a request id for SDK integration.

curl --request POST \
     --url https://api.withmono.com/v1/prove/initiate \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'mono-sec-key: <Your Secret Key>' \
     --data '{
    "reference": "testreference123",
    "redirect_url": "https://mono.co",
    "kyc_level": "custom", // or tier_1, tier_2, tier_3
    "identities": ["bvn", "address"], // required only when kyc_level is custom
    "bank_accounts": true,
    "customer": {
        "name": "Adebayo Adeyemi",
        "phone": "08012345678",
        "email": "test@example.com",
        "address": "20, Angel's Place, Eke street off NTA road, Ikeja Lagos",
        "identity": {
            "type": "BVN", // can either be BVN or NIN
            "number": "12345678900"
        }
    }
}'

Body Request Descriptions

{
    "status": "successful",
    "message": "Request completed successfully",
    "timestamp": "2025-01-10T21:47:35.919Z",
    "data": {
        "id": "reRVZW59A3Q123",
        "customer": "67d18b0770caaed57fe3tb2bw",
        "mono_url": "https://prove.mono.co/reRVZW59A3Q123",
        "reference": "testreference123",
        "redirect_url": "https://mono.co",
        "bank_accounts": true,
        "kyc_level": "custom",
        "identities": ["bvn", "address"],
        "is_blacklisted": false,
        "live_mode": true
    }
}

KYC Level Breakdown

• tier_1: Validating only the BVN and NIN numbers and verifying ownership of the submitted identity numbers with facial recognition.

• tier_2: Validating BVN, NIN, a government-issued identification document, and verifying ownership of the submitted document with facial recognition.

• tier_3: Validating BVN, NIN, government ID, and address, verifying ownership of the submitted documents with facial recognition, and confirming the user resides at the provided address.

• custom: Define required identity checks using the identities array. The widget dynamically renders only the configured identities while still requiring personal information and facial verification. At least one of bvn or nin must be included.

Step 2: User Session Access Setup

Users in this step can complete verification through two convenient methods: integrating the Prove web or mobile SDK using a request ID or accessing the verification process via a unique Prove Link (mono_url), which can also be sent via email for easy access. This can be achieved in either of the explained ways below:

Step 2a: SDK implementation

With step one out of the way, we can now proceed with this step to instantiate the prove widget via the vanilla js implementation.

What you simply need to do here is to update your Prove SDK widget with the requestid field, which you have already received from Step 1 above.

Here’s the JavaScript SDK example below, you can find more Prove SDKs here.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
  </head>

  <div>
    <button id="cta" onclick="window.prove.open()">Click Me</button>
  </div>

  <body>
    <script src="../index.js" type="module"></script>
    <script type="module">
      import Prove from "../index.js";

      const prove = new Prove({
        requestId: "reRVZW59A3Q00I",
        onLoad: () => console.log("LOADED"),
        onEvent: console.log,
        onSuccess: console.log,
      });

      prove.setup();

      window.prove = prove;
    </script>
  </body>
</html>

SDK Demo

You can find a demo web app that implements this flow here.

Step 2b: Instantiate the widget using the Mono URL.

To do this, send the user the mono_url gotten in the response from Step 1 (in this case, 'https://prove.mono.co/reRVZW59A3Q123'. They can open this link in their browser to complete the verification process.

Step 3: Identity Verification Onboarding.

To complete the verification, the user will be guided through a series of steps.

• First, your user will need to enter their phone number and date of birth, followed by selecting their preferred OTP method.

• Next, depending on the configured tier or custom identities, after receiving and inputting the OTP, they will be prompted to complete only the required checks (for example NIN/BVN, passport, driver's license, or address).

• Next, they will add their bank account details and grant permission for data access.

• They will then choose their access type and perform a facial recognition check.

Please note: There are two access types available to users: Continuous access and one-time access. Continuous access grants access to the user's data indefinitely, while the one-time access enables users to determine a time frame for the data access granted.

• Finally, they will have the option to save their data for future verifications before completing the process.

Upon successful completion, you'll receive a mono.prove.data_verification_successful webhook confirmation.

Manual Face-ID Verification

The Prove Face-ID Manual Review feature enables you to manually validate users whose automated facial recognition attempts fail repeatedly. These failures may occur due to poor lighting, visual impairments, low-quality selfies, or potential fraudulent activity.

After three unsuccessful automated attempts, the system automatically transitions the session into a manual review state and notifies the partner to review the submitted images via the Partner Dashboard.

Kindly follow the steps below to manually validate users:

1. Log in to the Mono Dashboard.

2. On the Prove module, navigate to awaiting review tab.

3. Click on the verification you want to review to open its details.

4. • From here, you can approve or reject the verification if the face-id matches or not
   • Once a verification is approved, its status will update to successful, and the corresponding webhooks and email notifications will be sent to the business.
   • If a verification is rejected, the system notifies the user via email and sends a verification.rejected webhook event to the business.

Liveness Check Image

By default, we return images associated with the user's BVN and NIN when you fetch customer details. The image captured during the user's liveness check is not returned.

If you require the liveness check image, please contact our support team at support@mono.co to have this feature enabled for your account. Once enabled, set the include_identity_images query parameter to true to get the image returned in the customer details response. If you do not require it, you can omit the parameter from your request.

Webhook Events

Mono Prove uses webhooks to deliver key information about identity verification sessions. Each time a verification event occurs, Mono sends a POST request to your designated URL.

Webhook Events

See the Prove Webhook Events page for the full event list, payload examples, and webhook handling guidance.

Resources

Webhook Events

Initiate Prove API

Fetch Customer Details

Fetch All Shared Customers Details

Blacklist Customer

Whitelist Customer

Revoke Data Access