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'll need your Mono secret key and a webhook URL. To get these, follow the steps below:

• Sign up on the Mono Dashboard. and complete KYC.

• Create an App and set the product to "Prove" to generate your Mono secret key. The Mono secret key is used to make API calls to most of Mono's endpoints, and should be passed in your headers as "mono-sec-key". You can check out this guide on how to create an app and obtain your secret key.

• Configure a webhook URL and add it to your dashboard. (For testing, use webhook.site to generate a temporary webhook URL. N.B not for production)

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": "tier_1", // or tier_2 or tier_3
    "bank_accounts": true,
    "customer": {
        "name": "Samuel Olamide",
        "email": "samuel.olamide@neem.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": "tier_1",
        "is_blacklisted": false
    }
}  

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.

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>

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 their tier, after receiving and inputting the OTP, they will be prompted to verify their NIN/BVN and provide a government-issued ID, such as a passport or driver's license, along with their 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.

• 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.

Mono Prove Webhooks

Mono Prove uses webhooks to deliver key information about identity verification sessions. When a verification event occurs (initiation, success, cancellation, or expiration), Mono sends a POST request to your designated URL. This allows you to receive and process verification updates, such as session status and customer data, within your system's workflow.

1. Verification Initiated Webhook (mono.prove.data_verification_initiated)

This webhook is triggered when the initiate session is successfully created.

{
    "event": "mono.prove.data_verification_initiated",
    "data": {
      "app": "67b5c78477237d041a069bd0",
      "business": "60cc8f95ba1772018c5c6b1d",
      "id": "PRVQ1B9JR5123",
      "status": "pending",
      "reference": "test-reference-03",
      "created_at": "2025-02-28T09:24:32.823Z",
      "kyc_level": "tier_1",
      "bank_accounts": false,
      "is_blacklisted": false,
      "meta": {
        "ref": "1234"
      }
    }
  }

2. Verification Successful Webhook (mono.prove.data_verification_successful)

This webhook is triggered when the customer data is verified and successfully shared with the business.

{
    "event": "mono.prove.data_verification_successful",
    "data": {
      "id": "PRVJM0POABY04",
      "customer": {
        "id": "67c07e5dcde95dbf8c2f2c7e",
        "name": "SAMUEL OLAMIDE",
        "email": "samuel@neem.co"
      },
      "reference": "ref-9",
      "status": "successful",
      "created_at": "2025-03-04T12:53:49.839Z",
      "kyc_level": "tier_1",
      "bank_accounts": true,
      "data_access": {
        "start_date": null,
        "end_date": null,
        "type": "permanent"
      },
      "app": "67b5c78477237d041a069bd0",
      "business": "60cc8f95ba1772018c5c6b1d"
    }

3. Verification Cancelled Webhook (mono.prove.data_verification_cancelled)

This webhook is triggered when a customer cancels their data verification.

{
    "event": "mono.prove.data_verification_cancelled",
    "data": {
      "id": "PRVG62L211UN2",
      "customer": {
        "id": "67c07e5dcde95dbf8c2f2c7e",
        "name": "SAMUEL OLAMIDE",
        "email": "samuel@neem.co"
      },
      "reason": "I am not comfortable sending my ID photo",
      "reference": "ref-7",
      "status": "cancelled",
      "created_at": "2025-03-03T15:01:15.587Z",
      "kyc_level": "tier_2",
      "bank_accounts": true,
      "app": "67b5c78477237d041a069bd0",
      "business": "60cc8f95ba1772018c5c6b1d"
    }

4. Verification Cancelled Webhook (mono.prove.data_verification_expired)

This webhook is triggered when a customer's data verification expires after 24 hours of non-completion.

{
    "event": "mono.prove.data_verification_expired",
    "data": {
      "id": "PRVXH82GO8123",
      "reference": "ref-6",
      "status": "expired",
      "created_at": "2025-03-03T12:20:20.829Z",
      "kyc_level": "tier_1",
      "bank_accounts": true,
      "app": "67b5c78477237d041a069bd0",
      "business": "60cc8f95ba1772018c5c6b1d",
      "attempts": 0, // otp authentication attempts
      "error_logs": [ //last 3 errors before link expiration
        {
          "timestamp": 1741006286345,
          "message": "Unable to complete request"
        },
        {
          "timestamp": 1741006398337,
          "message": "Unable to complete request"
        },
        {
          "timestamp": 1741009395153,
          "message": "Unable to complete request"
        }
      ]
    }

Resources

Initiate Prove API

Fetch Customer Details

Fetch All Shared Customers Details

Blacklist Customer

Whtelist Customer

Revoke Data Access