JavaScript Library for Web Verification

How to Generate Widget Using the Dojah CDN-hosted Javascript client library, you can install the Dojah widget into your application by simply adding a script tag to your HTML document and insert basic configuration parameters. Step 1: Add the Client Javascript Library Add the script tag before the end of the closing body tag of your desired HTML page where you desire to give users the ability to authorize access to a financial institution.

javascript

<script src="https://widget.dojah.io/widget.js"></script>

Adding the async attribute can cause the inline code to return undefined because the library may not be available at that moment. So avoid the use of async and defer for now.

Step 2: Configure the Javascript Client Library At this stage, you can now create a Dojah widget object by passing in your public key in javascript object representing your preferred configuration options.

javascript

const options = {
  app_id: app_id, //your app_id here
  p_key: p_key, //your production public key here
  type: 'custom',
  embed: true, //optional: embed is a boolean that states you want to embed the widget in an element
  container: "#embed-container", //optional: container is the element to embed the widget in 
  user_data: {
    first_name: {$first_name}, //optional
    last_name: {$last_name}, //optional
    dob: {$dob}, //YYYY-MM-DD Optional
    residence_country: 'NG', //optional
    email: {$email}//optional
  },
  gov_data : {
    "bvn": "123456789", //
    "nin": "123456789", //
  },
  metadata: {
    user_id: '12xxxxsxsxsxssx1',
  },
  
  config: {
    widget_id: ""  //this is generated from easyonboard here https://app.dojah.io/easy-onboard

  },
  onSuccess: function (response) {
    console.log('Success', response);
  },
  onError: function (err) {
    console.log('Error', err);
  },
  onClose: function () {
    console.log('Widget closed');
  }
};

const connect = new Connect(options);
const button = document.querySelector('#button-connect');
button.addEventListener('click', function () {
  connect.setup();
  connect.open();
});

Parameter	Type	Description
type	string	Widget Type: Values are ‘custom’, ‘verification’, ‘identification’, ‘verification’, ‘liveness’
app_id	string	Application Id, Get it from your dojah application dashboard here
p_key	string	Public Key, Get it from your dojah application dashboard here
reference_id	string	Reference ID, It can be passed to keep track of the verification steps (Started, Ongoing, Successful). NB: reference_id character length must be greater than 10
widget_id	string	Widget ID, Get it from your Easy Onboard application dashboard here
user_data	object	Automatically update the user data page, and thus skip the page
gov_data	object	Automatically update the government data page, and thus skip the page
metadata	object	Your application’s metadata to be passed back to you via webhook, onSuccess, or onError
onSuccess	function	Called when the user has completed all verification steps in the widget flow. The sample response data below is returned to this callback.
onError	function	Called when an error occurs before all verification steps are completed, preventing the user from finishing the flow.
embed	boolean	When set to `true`, renders the widget inline inside a specified DOM element instead of opening it as a modal overlay. Defaults to `false`.
container	string	A CSS selector pointing to the DOM element that will host the embedded widget. Required when `embed` is `true`.
onClose	function	Called when the user terminates the widget via the close button before completing all steps.

Embedding the Widget Inline

By default, the Dojah widget opens as a modal overlay on top of your page. If you prefer to render it inline within your existing page layout, use the embed and container options together.embed (boolean, optional) — Set this to true to switch the widget from modal mode to embedded mode. When embedded, the widget renders directly inside a DOM element on your page instead of appearing as a floating overlay. This is useful when you want the verification flow to feel like a native part of your application rather than a popup.container (string, optional) — A CSS selector that identifies the HTML element the widget should render inside. This is required when embed is set to true. The selector follows standard CSS syntax (e.g. "#embed-container" for an element with id="embed-container", or ".verify-section" for a class-based selector).Example usage:

<!-- Add a container element in your HTML -->
<div id="embed-container" style="width: 100%; max-width: 500px; height: 700px;"></div>

const options = {
  app_id: app_id,
  p_key: p_key,
  type: 'custom',
  embed: true,
  container: "#embed-container",
  config: { widget_id: "your-widget-id" },
  // ...other options
};

When to use embedded mode:

You want the widget to appear as part of your page flow (e.g. inside a settings panel, onboarding stepper, or dashboard section).
You need full control over the widget’s positioning, sizing, and surrounding layout.
You want to avoid the modal overlay blocking other page content.

Important: Make sure the container element exists in the DOM before calling connect.setup(). The element should have explicit dimensions (width/height) so the widget renders correctly within the allocated space.

Important Security Update: Proper Handling of SDK Verification CallbacksThe final verification decision should never rely on SDK callbacks (onSuccess, onError, onClose) alone. Always retrieve the actual verification status from your backend using the reference ID before granting access or approving onboarding.

onSuccess — All verification steps completed

The onSuccess callback is triggered when the user has completed all the verification steps configured in the widget flow. This confirms that every step — such as document capture, liveness check, government data entry, etc. — has been submitted by the user.Important: onSuccess confirms flow completion, not that the user passed all checks. A user may complete every step but still fail backend validation (e.g., document mismatch, failed liveness). Always verify the final result from your backend using the reference ID.

onError — Error before all steps are completed

The onError callback is triggered when an error occurs before all verification steps are completed. This prevents the user from finishing the flow. Common causes include:

Network connectivity issues
SDK initialization or configuration errors
Provider-side failures during a verification step
Unexpected interruptions during the flow

When onError fires, the verification is incomplete. Your application should handle this gracefully — for example, by prompting the user to retry.

onClose — Widget terminated via close button

Recommended ImplementationAfter the widget interaction, create a backend flow or confirmation page that retrieves the actual verification result using the reference ID generated during the verification process. You can retrieve the final verification details through:

Webhook notifications — Subscribe to services
Verification Details API — Get verification details

Possible Verification Statuses The verification result returned by the webhook or API may contain any of the following statuses:

Status	Description
Ongoing	The verification process is currently in progress.
Completed	The verification has been successfully completed and passed all checks.
Pending	The verification is awaiting further action or review.
Failed	The verification was completed but did not pass one or more verification checks.
Abandoned	The verification was started but not completed by the user.

Typescript implementation

If you want to use typescript on some classes that are not available now or in the future, you could look at extending the global ‘window’ interface. You can follow below steps to guide you: With typescript, you need to extend the global Window interface with additional properties. Create a new folder “types” Add a file “index.d.ts” Put below code inside your “index.d.ts” file

typescript

export { };
declare global {
    interface Window {
        Connect: any;
	//add more properties you would like to extend
    }
}

set your compilerOptions “typeRoots” property to path of your type folder E.g [”./src/types”] Use the extended window property anywhere like this:

typescript

const connect = new window.Connect(options);

Step 3: Handle the Verification Callbacks When the user completes all verification steps, the onSuccess callback is invoked with the verification response data. If an error occurs before all steps are completed, onError is called instead. If the user closes the widget via the close button, onClose is triggered. Use the overall status (response.status (Boolean, i.e true or false)) to ascertain if the request failed or succeeded.

Webhook NotificationsYou can receive the same data below (also passed to onSuccess and onError) via a webhook call.Register your url for webhook calls here and ensure kyc.widget is the service you are subscribed to.In Config object Kindly set webhook object value to true (Boolean)Example : webhook : true

The Sample response data after successful verification

Response

{
    aml: {
        status: false
    },
    data: {
        id: {
            data: {
                id_url: "https://images.dojah.io/id_sample_id_1720624047.jpg",
                id_data: {
                    extras: "",
                    last_name: "John",
                    first_name: "Doe",
                    mrz_status: "",
                    date_issued: "2019-01-01",
                    expiry_date: "2020-01-01",
                    middle_name: "",
                    nationality: "Nigerian",
                    date_of_birth: "1990-01-01",
                    document_type: "National ID",
                    document_number: "123456789"
                },
                back_url: "https://images.dojah.io/id_sample_id_1720624047.jpg"
            },
            status: true,
            message: "Successfully verified your id"
        },
        email: {
            data: {
                email: "abc@gmail.com"
            },
            status: true,
            message: "abc@gmail.com validation Successful"
        },
        index: {
            data: {},
            status: true,
            message: "Successfully continued to the main checks."
        },
        selfie: {
            data: {
                selfie_url: "https://images.dojah.io/selfie_sample_image_1720624219.jpg"
            },
            status: true,
            message: "Successfully validated your liveness"
        },
        countries: {
            data: {
                country: "Nigeria"
            },
            status: true,
            message: "Successfully continued to the next step."
        },
        user_data: {
            data: {
                dob: "1990-12-03",
                last_name: "John",
                first_name: "Doe"
            },
            status: true,
            message: ""
        },
        business_id: {
            image_url: "https://images.dojah.io/selfie_sample_image_1720624219.jpg",
            business_name: "ABC Company LIMITED",
            business_type: "Business",
            business_number: "1237654",
            business_address: "",
            registration_date: ""
        },
        phone_number: {
            data: {
                phone: "234810123456"
            },
            status: true,
            message: "2348103817187 validation Successful"
        },
        business_data: {
            business_name: null,
            business_type: "BN",
            business_number: null,
            business_address: null,
            registration_date: null
        },
        government_data: {
            data: {
                bvn: {
                    entity: {
                        bvn: "222222222222",
                        nin: "",
                        email: "",
                        title: "",
                        gender: "Male",
                        customer: "6bb82c41-e15e-4308-b99d-e9640818eca9",
                        image_url: "https://images.dojah.io/id_John_Doe_1720615487.jpg",
                        last_name: "John",
                        first_name: "Doe",
                        middle_name: "Anon",
                        nationality: "",
                        name_on_card: "",
                        watch_listed: "",
                        date_of_birth: "01-Jun-1982",
                        lga_of_origin: "",
                        phone_number1: "08011111111",
                        phone_number2: "",
                        marital_status: "",
                        enrollment_bank: "",
                        state_of_origin: "",
                        level_of_account: "",
                        lga_of_residence: "",
                        enrollment_branch: "",
                        registration_date: "",
                        state_of_residence: "",
                        residential_address: ""
                    }
                },
               nin: {
                entity: {
                nin: "1234567891",
                firstname: "John",
                middlename: "Doe",
                surname: "Anon",
                maidenname: "",
                telephoneno: "0901234567",
                state: "",
                place: "",
                profession: "ZOOLOGY",
                title: "",
                height: "167",
                email: "",
                birthdate: "1960-01-01",
                birthstate: "",
                birthcountry: "Not Available",
                centralID: "",
                documentno: "",
                educationallevel: "tertiary",
                employmentstatus: "unemployed",
                othername: "",
                pfirstname: "",
                pmiddlename: "",
                psurname: "",
                nspokenlang: "YORUBA",
                ospokenlang: "",
                religion: "christianity",
                residence_Town: "",
                residence_lga: "Alimosho",
                residence_state: "Lagos",
                residencestatus: "birth",
                residence_AddressLine1: "No 2 Anon house, John does estate, Lagos state, Nigeria",
                residence_AddressLine2: "",
                self_origin_lga: "",
                self_origin_place: "",
                self_origin_state: "",
                signature: null,
                nationality: null,
                gender: "Female",
                trackingId: "",
                customer: "1234444y373737373737373737",
                image_url: "https://images.dojah.io/id_SANDBOX_1721830110.jpg"
              }
          }
            },
            status: true,
            message: ""
        },
        additional_document: [
            {
                document_url: "https://dojah-image.s3.amazonaws.com/66bcc73a4ff8e1003100454212aec768-3344-4df5-88f6-7e723c46cbb0.jpeg",
                document_type: "image"
            }
        ]
    },
    value: "123456",
    id_url: "https://images.dojah.io/id_sample_id_1720624047.jpg",
    status: true,
    id_type: "BVN",
    message: "Successfully completed the verification.",
    back_url: "https://images.dojah.io/id_sample_id_1720624047.jpg",
    metadata: {
        ipinfo: {
            as: "AS29465 MTN NIGERIA Communication limited",
            isp: "MTN NIGERIA Communication limited",
            lat: 6.4474,
            lon: 3.3903,
            org: "MTN Nigeria",
            zip: "",
            city: "Lagos",
            proxy: false,
            query: "102.89.34.49",
            mobile: true,
            status: "success",
            country: "Nigeria",
            hosting: true,
            district: "",
            timezone: "Africa/Lagos",
            region_name: "Lagos"
        },
        device_info: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36"
    },
    selfie_url: "https://images.dojah.io/selfie_sample_image_1720624219.jpg",
    reference_id: "DJ-31038041E0",
    verification_url: "https://app.dojah.io/verifications/bio-data/49fd74a4-8181-4ce8-a87a-0e63f7159257",
    verification_mode: "LIVENESS",
    verification_type: "RC-NUMBER",
    verification_value: "123456",
    verification_status: "Completed"
}

SDKs & Libraries

Embedding the Widget Inline

​Typescript implementation

Typescript implementation