youverify-sdk

Youverify Web SDK

Browser wrapper for Youverify's vForm

Table of Contents

• Features
• Installation
• Modules
  • vForm
  • Liveness Check
  • Document Capture
• Options
  • vForm
  • Liveness Check
  • Document Capture

Features

Installation

Using npm:

$ npm install youverify-sdk

Using yarn:

$ yarn add youverify-sdk

Using CDN:

Modules

vForm

The vForm module is available for integration to your web app if you wish to use vForm

Usage

Initialization:

1. To use the vForm module in your project, you have to first pass your custom options to it like so:

const vFormModule = new YouverifySDK.vForm(options)

Checkout a list of the valid options for the vForm module

Example:

const vFormModule = new YouverifySDK.vForm({
  vFormId: `Id of vForm`,
  publicMerchantKey: `<YOUR PUBLIC MERCHANT KEY>`,
  personalInformation: {
    firstName: "John",
    lastName: "Doe",
  },
  metadata: {},
  onSuccess: () => {
    // vForm has submitted successfully
  },
  onClose: () => {
    // close button was clicked
  },
})

2. Call initialize on the vFormModule object

try {
  vFormModule.initialize();
} catch (error) {
  // handle validation error
}

Start Process

3. Call start() on the vFormModule object to show the pop-up modal and start the process.

vFormModule.start()

Note: Once the vForm process is completed and successfull, the onCompleted callback supplied will be triggered. If none was supplied, nothing happens.

Liveness Check

The Liveness Check module is available for integration to your web app if you wish to allow your users perform liveness checks.

Usage

Initialization:

1. To use the liveness module in your project, you have to first pass your custom options to it like so:

const livenessCheckModule = new YouverifySDK.liveness(options)

Checkout a list of the valid options for the liveness check module

Example:

const livenessCheckModule = new YouverifySDK.liveness({
  publicMerchantKey: `<YOUR PUBLIC MERCHANT KEY>`,
  personalInformation: {
    firstName: "John",
  },
  onSuccess: () => {
    // liveness check was successful
  },
  onFailure: () => {
    // liveness check was not successful
  },
})

2. Call initialize on the livenessCheckModule object

try {
  livenessCheckModule.initialize();
} catch (error) {
  // handle validation error
}

Start Process

3. Call start() on the livenessCheckModule object to show the pop-up modal and start the process.

vFormModule.start()

Note: Once the liveness process is completed and successfull, the onSuccess callback supplied will be triggered. If none was supplied, nothing happens.

Document Capture

The Document Capture module is available for integration to your web app if you wish to allow your users carry out identity documents capture.

Usage

Initialization:

1. To use the document capture module in your project, you have to first pass your custom options to it like so:

const documentCaptureModule = new YouverifySDK.documentCapture(options)

Checkout a list of the valid options for the document capture module

Example:

const documentCaptureModule = new YouverifySDK.documentCapture({
  publicMerchantKey: `<YOUR PUBLIC MERCHANT KEY>`,
  type: "passport",
  personalInformation: {
    firstName: "John",
  },
  onSuccess: () => {
    // result received from document
  },
  onFailure: () => {
    // could not get result from document
  },
})

2. Call initialize on the documentCaptureModule object

try {
  documentCaptureModule.initialize();
} catch (error) {
  // handle validation error
}

Start Process

3. Call start() on the documentCaptureModule object to show the pop-up modal and start the process.

documentCaptureModule.start()

Note: Once the document capture process is completed and successfull, the onSuccess callback supplied will be triggered. If none was supplied, nothing happens.

Options

vForm Options

These are the valid options to pass to the vFormModule instance

{
  // `vFormId` is the Id of the vForm you would like the SDK to open
  "vFormId": "<YOUR-VFORM-ID>", // required

  // `publicMerchantKey` is available in your YVOS profile
  "publicMerchantKey": "<YOUR-PUBLIC-MERCHANT-KEY>", // required

  // `personalInformation` is an object containing a list of predefined user attributes to be passed to the SDK for personalization of the experience. Attributes passed here should typically exist in the vForm created, else, they will be ignored.
  "personalInformation": {
    "firstName": "John", // optional
    "lastName": "Doe", // optional
    "middleName": "Bruno", // optional
    "email": "[e-mail]", // optional
    "mobile": "+2348*********", // optional
    "gender": "MALE", // optional [MALE, FEMALE or NOT_IDENTIFIED]
  },

  // `metadata` is any other information you would like to pass to your webhook URL
  "metadata": { // optional
    // your custom keys
  },

  // `onComplete` callback is a function called onced the vForm entry has been submitted and process completed successfully
  "onComplete": () => { // optional
    // custom logic here
  }

  // `onSuccess` callback is a function called onced the vForm entry has been submitted successfully
  "onSuccess": (data) => { // optional
    // custom logic here
  }

  // `onFailure` callback is a function called onced the vForm entry submission fails due to some reasons
  "onFailure": (error) => { // optional
    // custom logic here
  }

  // `onClose` callback is a function called onced the vForm process has been cancelled or modal closed
  "onClose": () => { // optional
    // custom logic here
  }
}

Liveness Check Options

These are the valid options to pass to the livenessCheckModule instance

{
  // `publicMerchantKey` is available in your YVOS profile
  "publicMerchantKey": "<YOUR-PUBLIC-MERCHANT-KEY>", // required

  // `personalInformation` is an object containing a list of predefined user attributes to be passed to the SDK for personalization of the experience
  "personalInformation": {
    "firstName": "John", // optional
  },

  // `metadata` is any other information you would like to pass to your webhook URL
  "metadata": { // optional
    // your custom keys
  },

  // `onCompleted` callback is a function called onced the liveness check was successful
  "onSuccess": (data) => { // optional
    // Sample data object
    /*
      {
        "parentId": null,
        "method": "liveness",
        "components": [
            "liveness"
        ],
        "faceImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA0gAAAISCAYAAAD2",
        "passed": false,
        "Country": "NG",
        "isConsent": true,
        "metadata": {},
        "businessId": "61d880f1e8e15aaf24558f1a",
        "requestedAt": "2022-02-11T13:56:41.226Z",
        "createdAt": "2022-02-11T13:56:41.237Z",
        "lastModifiedAt": "2022-02-11T13:56:41.237Z",
        "_createdAt": "2022-02-11T14:56:4141+01:00",
        "_lastModifiedAt": "2022-02-11T14:56:4141+01:00",
        "id": "62066b187a09d0dd4fa21ea1"
      }
    */
   // custom logic here
  }

  // `onRetry` callback is a function called onced the liveness process failed and is being retried
  "onRetry": (data) => { // optional
    // custom logic here
  }

  // `onCancel` callback is a function called onced the liveness process is cancelled
  "onCancel": (data) => { // optional
    // custom logic here
  }

  // `onFailure` callback is a function called onced the liveness check fails
  "onFailure": (error) => { // optional
    // custom logic here
  }

  // `onClose` callback is a function called onced the liveness check process modal has been closed
  "onClose": () => { // optional
    // custom logic here
  }
}

Document Capture Options

These are the valid options to pass to the documentCaptureModule instance

{
  // `publicMerchantKey` is available in your YVOS profile
  "type": "passport", // required, one of [nin, passport, drivers-license, pvc]
  // `publicMerchantKey` is available in your YVOS profile
  "publicMerchantKey": "<YOUR-PUBLIC-MERCHANT-KEY>", // required

  // `personalInformation` is an object containing a list of predefined user attributes to be passed to the SDK for personalization of the experience
  "personalInformation": {
    "firstName": "John", // optional
  },

  // `metadata` is any other information you would like to pass to your webhook URL
  "metadata": { // optional
    // your custom keys
  },

  // `onSuccess` callback is a function called onced the document capture has a result
  "onSuccess": (data) => { // optional
    // Sample data object
    /* {
          "licenseDetails": {
              "vehicleClass": "D",
              "conditions": null,
              "endorsements": "P"
          },
          "firstName": "",
          "middleName": "",
          "lastName": "",
          "status": "unavailable",
          "fullName": "EHICHIOYA, FAMOUS PRIOR",
          "components": [
              "id_capture"
          ],
          "dateOfBirth": "1989-04-04T00:00:00.000Z",
          "dateOfExpiry": "2026-04-04T00:00:00.000Z",
          "gender": "M",
          "rawMRZString": "",
          "fullDocumentFrontImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA0gAAAISCAYAAAD2h",
          "fullDocumentBackImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA0gAAAISCAYAAAD2",
          "faceImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA0gAAAISCAYAAAD2he/+AAAAAXNSR0IArs4c6Q",
          "address": "250 Borno way yaba Lagos",
          "issuingAuthority": "Lagos State",
          "maritalStatus": "Married",
          "placeOfBirth": "Ikoyi",
          "signatureImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA0gAAAISCAYAAAD2he/+AAAAAXNSR",
          "dateOfIssue": "2021-05-26",
          "Country": "NG",
          "notifyWhenIdExpire": false,
          "isConsent": true,
          "documentType": "drivers_license",
          "method": "documentCapture",
          "documentNumber": "SMK862xxxxxx",
          "metadata": {},
          "businessId": "61d880f1e8e15aaf24558f1a",
          "requestedAt": "2022-02-11T06:56:59.104Z",
          "createdAt": "2022-02-11T06:56:59.107Z",
          "lastModifiedAt": "2022-02-11T06:56:59.107Z",
          "_createdAt": "2022-02-11T07:56:5959+01:00",
          "_lastModifiedAt": "2022-02-11T07:56:5959+01:00",
          "id": "620608ba6d4a3ca32dff2358"
        }
    */
    // custom logic here
  }

  // `onFailure` callback is a function called onced the document capture fails
  "onFailure": (error) => { // optional
    // custom logic here
  }

  // `onCancel` callback is a function called onced the document capture process is cancelled
  "onCancel": (data) => { // optional
    // custom logic here
  }

  // `onClose` callback is a function called onced the document capture modal has been closed
  "onClose": () => { // optional
    // custom logic here
  }
}

Credits

This SDK is developed and maintained solely by Youverify

License

MIT License