Zero Hash KYC as a service

Customer Verification

To take advantage of this add-on product, platforms must talk to the Zero Hash sales team.

Overview

Zero Hash’s customer verification (KYC) web client SDK enables secure collection and verification of customer data, without requiring the platform to integrate to a third party KYC vendor or handle sensitive data.

An onboarding access token, retrieved via an API call, is required for you to invoke the web SDK. The onboarding flow can then be invoked via a Javascript call, with the acquired onboarding access token.

Acquire an onboarding access token by making an API call to the ZeroHash API server.
Invoke web flow by executing a Javascript function made available through the Zero Hash Web SDK and passing the onboarding access token.
Wait for a webhook response on your customer’s KYC status with Zero Hash.

Step 1. Acquire an onboarding access token

`POST /participants/onboarding_token`

To invoke the web SDK, you must request a temporary onboarding access token for each KYC verification event. This should be done in advance of rendering the onboarding page.

Generating an onboarding access token must be initiated on the server side. You must provide an <email> query parameter for the customer who will undergo KYC. This enables Zero Hash to uniquely identify participants and create a tie between our system and yours.

All API requests are authenticated using your signed API key. For detailed API usage, please refer to our online documentation.

Request body:

Parameter	Description	Type
email	Customer email address, required Note: Zero Hash will validate that the email is a correctly formatted email, and that the value is unique per-platform	string
phone_number	The phone number of the participant, optional	string

Additional fields in response:

Parameter	Description	Type
token	Onboarding access token which gives the end customer permission to go through KYC	string

Possible responses:

Status code	Description
200	The JWT generated successfully
400 Not found	Platform does not exist
403 Forbidden	Invalid request or platform is not configured by Zero Hash for this KYC track

Sample request

const postOnboardingToken = () => {
  const body = {
    email: "[email protected]",
    phone_number: "33512345678"
  }
  const timestamp = Math.round(Date.now() / 1000)
  const payload = timestamp + 'POST' + '/participants/onboarding_token' + JSON.stringify(body)
  const decodedSecret = Buffer.from(apiSecret, 'base64')
  const hmac = crypto.createHmac('sha256', decodedSecret)
  const signedPayload = hmac.update(payload).digest('base64')

  // SET HEADERS
  const headers = {
    'X-SCX-API-KEY': 'public_key',
    'X-SCX-SIGNED': signedPayload,
    'X-SCX-TIMESTAMP': timestamp,
    'X-SCX-PASSPHRASE': 'passphrase'
  }
  const options = {
    headers,
    body,
    json: true
  }

  return request.post(`https://api.zerohash.com/participants/onboarding_token`, options)
}

Sample Response

{
  "message": {
      "email": "[email protected]",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
    }
}

Step 2. Invoke web flow

Installation methods

Option 1: Download Release Bundle

Download the Zero Hash web SDK release bundle:
- https://github.com/seedcx/zh-web-sdk/releases
Copy index.js to somewhere in your code where it is public and accessible
- Alternatively you may include it in your build process with other frontend assets
Add the following code to your HTML <head> section: <script type="module" src="zh_web_sdk/dist/index.js"></script>
The Zero Hash SDK class will be available at window.zerohash

Note: The <script> type property must be module.

Option 2: Direct CDN Reference

Will be implemented in a future release.

Option 3: npm package (recommended)

cd to your node/npm project
Run npm i zh-web-sdk

Quick Setup

Follow the adjacent specifications. * Note: For Quick Setup in the Cert environment, use “https://onboarding.cert.zerohash.com/”

import ZeroHashSDK from "zh-web-sdk";

// Initialize SDK
const sdk = new ZeroHashSDK({
    zeroHashOnboardingURL: "https://onboarding.zerohash.com/"
});

// Set the user onboarding JWT retrieved for a particular user
// A user onboarding JWT before the user can proceed with the onboarding flow.
sdk.openOnboardingModal({
    userOnboardingJWT: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9." +
        "eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ." +
        "SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
});

Verification results

Webhooks

Zero Hash pushes KYC results via a webhook.

In order to accommodate, Zero Hash needs a return URL where we can send your results. As of today, these are configured manually by Zero Hash until we enable a developer interface.

Manual check

If you want to manually check the participant status, you can always acquire an up-to-date state of the participant via: GET /participants/:email

Keep in mind:

We don't recommend polling as the primary method for getting verification results, but rather as a secondary check or failsafe
If for some reason the webhook request fails, Zero Hash will re-attempt with an exponential backoff up to 10 times

Design and placement

For the best user experience, try to initialize the SDK in the center of the screen for desktop browsers, or in a new tab for mobile browsers.

The Zero Hash SDK iframe resizes according to the container, so your container does not need to have a static size.