zkKYB - Know Your Business

Use Case

To reduce development costs, you can use the zkMe KYB Widget to handle the entire business verification process. Users can complete the full KYB verification directly on your web/H5 application, minimizing user churn by eliminating the need to navigate to another page.

---

zkMe KYB Widget Process

The KYB verification flow consists of the following steps:

Step 1: Enter the service authorization Widget page; the user confirms and proceeds to the next step.

Step 2: Email verification login.

Step 3: Fill in company basic information.

Step 4: Fill in UBO (Ultimate Beneficial Owner) / SMO (Senior Managing Official) information.

Step 5: Trigger controller KYC/PoA verification for each controlling person.

Step 6: Upload corporate documents.

Step 7: Submit for review. The application status will then move to "Info Submitted" and await manual review by the zkMe compliance team.

---

Integration via NPM

You can refer to @zkmelabs/kyb-widget and please make sure to use the latest version.

Installation

pnpm add @zkmelabs/kyb-widget

# or
yarn add @zkmelabs/kyb-widget

# or
npm install @zkmelabs/kyb-widget

Getting Started

Step 1. Import styles

import '@zkmelabs/kyb-widget/dist/style.css'

Step 2. Create a new ZkMeKybWidget instance

import { ZkMeKybWidget, type Provider } from '@zkmelabs/kyb-widget'

const provider: Provider = {
  async getAccessToken() {
    // -------------------------TODO-------------------------
    // Request a new token from your backend service and return it to the widget.
    // For the access token, see https://docs.zk.me/hub/start/onboarding/integration/js-sdk/zkkyb#access-token
    // ------------------------------------------------------
    return fetchNewToken()
  },

  async getExternalID() {
    // -------------------------TODO-------------------------
    // `ExternalID` represents the unique identifier of this user in your system.
    // Typical examples include a corporate e-mail address, phone number,
    // or an internal user ID. Use the same identifier consistently
    // whenever you query or verify this user's KYB status.
    // ------------------------------------------------------
    return [externalID]
  },

}

const zkMeKybWidget = new ZkMeKybWidget(
  // -------------------------TODO-------------------------
  appId, // This parameter means the same thing as "mchNo"
  'YourDappName',
  provider,
  {
      programNo: 'YourProgramNo' // You can find the Program No in the ‘Configuration’ section of your KYB dashboard
      // For other options, please refer to the table below
  }
  // ------------------------------------------------------
)

NOTE: The specific configuration for the "option" parameter is shown in the table below

Param	Type	Description
options.programNo	string	If you have activated multiple programs running in parallel, please pay attention to this setting: The param can be found in Dashboard and please make sure the program is enabled. The SDK will take the number of the first activated program as the default value if this parameter is not provided in the code.

Step 3. Listen to the kybFinished widget events to detect when the user has completed the zkKYB process.

function handleKybFinished(results) {
  const { status, externalID, zkMeAccount, programNo } = results

  if (status === 5 && externalID === provider.getExternalID().toLowerCase()) {
    // -------------------------TODO-------------------------
    // The user has successfully completed zkKYB verification.
    // Prompt the user that verification has been completed.
    // ------------------------------------------------------
    console.log(`KYB verification completed for ${externalID}`)
  }
}

zkMeWidget.on('kybFinished', handleKybFinished)

Event Callback Parameters

The kybFinished event callback receives a results object with the following properties:

Name	Type	Description
status	int	Indicates the current verification status of the KYB process. Status codes are defined as follows: 1 – Verification Started 2 – Info Submitted 3 – Under Review 4 – Resubmission Required 5 – Verification Passed 6 – Verification Failed
externalID	string	The entity identifier from your system, echoed back by the SDK. This is the same value you returned as externalID in the getExternalID() function (for example, a corporate email address, phone number, or an internal user ID).
zkMeAccount	string	The zkMe internal account identifier.

Step 4. Launch the zkMe KYB widget and it will be displayed in the center of your webpage.

// This is the code to launch our widget on your page
button.addEventListener('click', () => {
  zkMeKybWidget.launch()
})

---

Helper functions

verifyKybWithZkMeServices()

Before launching the widget, you should check the zkKYB status of the user and launch the widget when the check result is false.

Function

import { verifyKybWithZkMeServices } from '@zkmelabs/kyb-widget'

// zkKYB
const { status, statusDesc } = await verifyKybWithZkMeServices(
  appId, // Your unique App ID (mchNo)
  externalID, // The user's unique identifier (e.g., corporate email)
  accessToken, // The access token obtained from https://docs.zk.me/hub/start/onboarding/integration/js-sdk/zkkyb#access-token
  options // Optional configurations are detailed in the table below
)

Name	Type	Description
appId	string	This parameter means the same thing as "mchNo"
externalID	string	The unique identifier provided by you to reference the KYB entity to be verified. This should match the getExternalID() passed by provider.getExternalID.
accessToken	string	The access token obtained from zkKYB - Know Your Business
options.programNo	string?	If you have activated multiple programs running in parallel, please pay attention to this setting: The param can be found in Dashboard and please make sure the program is enabled. The SDK will take the number of the first activated program as the default value if this parameter is not provided in the code.

Return

---

How to Generate an Access Token with API_KEY

To use your API_KEY to obtain an accessToken, you will need to make a specific HTTP request. Here's how you can do it:

NOTE: The generated accessToken is valid for 30 minutes and will expire automatically after that.

Endpoint

POST https://agw.zk.me/kybpopup/api/generate-access-token

Please remember to modify the Content-Type in the request header to application/json. Failing to do so might result in a Parameter Error response.

Request

Response

---

ZkMeKybWidget instance methods

launch()

Launch the zkMe KYB widget and it will be displayed in the center of your webpage.

launch(): void

on()

Listen to zkMe KYB widget events.

on(event: 'kybFinished', callback: KybFinishedHook): void;
on(event: 'close', callback: () => void): void;

hide()

Hide the zkMe widget.

hide(): void

destroy()

Remove the message event listener registered by the zkMe widget from the window and destroy the DOM node.

destroy(): void

---