User Onboarding

Web application

Example with React:

import React from 'react';
import ZeroHashSDK, { AppIdentifier } from 'zh-web-sdk';

const App = () => {
  const sdk = new ZeroHashSDK({
    zeroHashAppsURL: "https://web-sdk.cert.zerohash.com",
    userOnboardingJWT: "<JWT_TOKEN_HERE>"
  });

  sdk.openModal({appIdentifier: AppIdentifier.ONBOARDING})
  return <></>;
}

export default App;

📘

You can also get a token for the onboarding module another way. See Acquire an onboarding access token.

Choose an onboarding flow

openModal accepts an optional onboardingFlow parameter for AppIdentifier.ONBOARDING. It selects the onboarding experience that the SDK shows. Other app identifiers ignore it.

import { AppIdentifier, OnboardingFlow } from 'zh-web-sdk';

sdk.openModal({
  appIdentifier: AppIdentifier.ONBOARDING,
  jwt: "<JWT_TOKEN_HERE>",
  onboardingFlow: OnboardingFlow.FULL_WITHOUT_TAX, // Optional: defaults to OnboardingFlow.FULL_WITH_TAX
});

Before you use onboardingFlow:

• Ask your account team to turn on the new onboarding flows for your platform. Until they do, the SDK ignores onboardingFlow and shows the current flow.
• On the web, use zh-web-sdk 3.12.0 or later to send a value. Older versions cannot send the parameter, so they get full_with_tax. In a mobile WebView, send onboardingFlow in the OPEN_MODAL payload. See Open Modal.
• For tax_only, use a client access token. See Tax certification for existing participants.

Each time you call openModal, send the flow that you want. If you omit it, the SDK uses full_with_tax. It does not reuse the value from an earlier call. If you send a value that the SDK does not recognize, it also uses full_with_tax.

For what the customer sees in each flow, see Tax Data Collection - KYCaaS.

Tax certification for existing participants

Use OnboardingFlow.TAX_ONLY to collect a tax certification from a participant who is already onboarded. This works for participants onboarded through the SDK and for participants created through the API.

1. On your server, request a client access token for the participant. Send their participant_code and the update-participant permission:

{
  "permissions": ["update-participant"],
  "participant_code": "CUST01",
  "reference_id": "a81bc81b-dead-4e5d-abff-90865d1e13b1"
}

2. Open the Onboarding SDK with that token and onboardingFlow: OnboardingFlow.TAX_ONLY:

import { AppIdentifier, OnboardingFlow } from 'zh-web-sdk';

sdk.openModal({
  appIdentifier: AppIdentifier.ONBOARDING,
  jwt: '<CLIENT_ACCESS_TOKEN>',
  onboardingFlow: OnboardingFlow.TAX_ONLY,
});

🚧

Use a client access token

The onboarding access token from POST /participants/onboarding_token identifies the user by email and is for new users only. tax_only needs a token issued for an existing participant_code.

In tax_only:

• The customer sees the information that zerohash has on file, read-only, and the tax certification. If zerohash has no tax ID on file, the customer enters one.
• The SDK does not show the terms again if the customer already accepted them.
• The SDK does not run identity verification again. ONBOARDING_COMPLETED reports the participant's existing KYC status, or UNKNOWN. Do not wait for a new KYC result webhook.

Mobile application (WebView)

You do not need to install or include zh-web-sdk in a mobile app. A zerohash proxy server calls the SDK for you.

Events

The SDK sends events from the UI to the native app with the postMessage API. Handle these events in your WebView component. The SDK sends these events:

Messages

After you receive SDK_MOBILE_READY, you can control the WebView with postMessage. The WebView accepts these messages.

Open Modal

Opens the modal for the app identifier, with the JWT that you provide.

{type: "OPEN_MODAL", payload: {jwt: "<JWT_HERE>", appIdentifier: "onboarding"}}

Open the modal with the tax certification only, for a participant who is already onboarded. Use a client access token. See Tax certification for existing participants.

{type: "OPEN_MODAL",
  payload: {
    jwt: "<CLIENT_ACCESS_TOKEN>",
    appIdentifier: "onboarding",
    onboardingFlow: "tax_only"
  }
}

Open the modal on the edit-address page:

{type: "OPEN_MODAL",
  payload: {
    jwt: "<JWT_HERE>",
    appIdentifier: "onboarding",
    navigate: {to: "edit-address"}
  }
}

Close Modal

Hides the modal and keeps its current state. If you reopen the modal in the same instance, the state stays the same.

{type: "CLOSE_MODAL", payload:{appIdentifier: "onboarding"}}

📘

Closing and opening the modal works as pause and resume, because the UI keeps its state. To restart the flow, create a new modal instance.

For more about the SDK in WebViews, see Integration with Mobile Apps.