SDK reference, Incode Web SDK 2 Reference / Web SDK 2 Individual Modules

KYB Checks Module

Warning

This guide is specific to Web SDK 2.x. For Web SDK 1.x, you can find documentation here.

Do not attempt to upgrade or implement without support. Contact your Incode representative to check if you are a candidate for this upgrade.

The KYB Checks module (EKYB_CHECKS) runs business verification checks. It asks the user for the business country first, then shows the fields that country needs for the checks that your Flow or Workflow selects, and submits them. You review the check results in Dashboard.

The form is built for each country, so the fields, labels, and rules come from the service and can differ between countries. The module needs an onboarding session whose Flow or Workflow includes EKYB_CHECKS.

This module follows a form-based pattern variant: a form that is served for the chosen country, with no pre-fill from earlier modules. For the form-based eKYB module, see Module: eKYB.

How the form works

  1. The module loads and shows a country field.
  2. When the user picks a country, the module loads that country's form. Only the country field shows while the new form loads.
  3. The user fills in the fields and continues. The module validates the form and submits it.
  4. On success, the module calls onFinish with a referenceId.

A field can be a text input, a dropdown, a phone input, or a list where the user adds several entries. Each field shows its own validation messages.

Tag

<incode-kyb-checks> is a standard Web Component. Importing the UI subpath registers the custom element; importing the CSS applies the module's styles.

import '@incodetech/web/kyb-checks';
import '@incodetech/web/kyb-checks/styles.css';

Properties

Property Type Required Description
config KybChecksConfig ❌ Module configuration. A Flow or Workflow supplies it.
manager KybChecksManager ❌ A manager you created, to drive the module yourself.
onFinish (result?: KybChecksResult) => void ❌ Called when the module finishes. result.referenceId identifies the check run.
onError (error?: string) => void ❌ Called on a terminal error, such as an expired session. Load and submit errors stay in the module's error state.

Configuration

KybChecksConfig is the shape the Flow or Workflow serves. It is exported from @incodetech/core/kyb-checks.

type KybChecksConfig = {
  modules?: KybCheckModuleKey[];
};

type KybCheckModuleKey =
  | 'identity'
  | 'address'
  | 'statusEntityType'
  | 'personAssociation'
  | 'webPresence'
  | 'websiteAnalysis'
  | 'industryInfo'
  | 'financialIntelligence'
  | 'groupStructure';
Option Description
modules The checks that the Flow or Workflow selects. The service uses them to decide which fields the form asks for. A selected check that a country cannot run is left out of that country's form.

You don't normally set this configuration yourself. Select the checks in Dashboard.

Result

onFinish receives a KybChecksResult:

type KybChecksResult = {
  referenceId?: string;
};

The result carries only the reference. The outcome of each check is not returned to the browser; review it in Dashboard or retrieve it from your backend.

State machine

KybChecksState is a discriminated union over status:

Status Description
loading Loading the first form, the country picker.
form Rendering the fields.
submitting Submitting the form.
error A load or a submit failed. errorKind is 'load' or 'submit'. canRetry says whether retry() is offered.
misconfigured KYB is not in the session's flow, the session is closed, or the served form is not one this SDK version supports.
finished Terminal. result holds the referenceId.
closed The user dismissed the module.

Form-state properties

These fields exist only when status === 'form'.

Property Type Description
title KybText | undefined Title for the form.
sections KybChecksSection[] Sections in display order. The first holds the country field. Each section has id, an optional title, and fields.
values KybFieldValues Current values. A list field holds an array of strings; every other field holds a string.
errors KybFieldErrors Field-name map of KybText messages.
isRefetching boolean true while the form for a newly chosen country loads.
canSubmit boolean false until a country is chosen and its form has loaded, and while a new form loads.

A KybText is { key, text, params? }. Translate key with your own translations and show text when there is none. A params value can itself be a KybText; translate it before you insert it.

Errors and retries

After a load error, retry() is always offered. After a submit error, retry() is offered only when the service rejected the request, because otherwise the checks may already have run and a retry could run them twice. When canRetry is false, offer close() instead. The built-in screen does this for you.

API methods

Method Purpose Callable when
load() Load the first form, the country picker. initial
setField(name, value, isValid?) Set one field and clear its error. Setting the country loads that country's form. Pass isValid: false when the input knows the value is malformed, as a phone input does. form
submit() Validate the form and, when it passes, run the checks. form
retry() Repeat the request that failed. error with canRetry
close() Close the module. form, error, misconfigured
import { createKybChecksManager } from '@incodetech/core/kyb-checks';

const manager = createKybChecksManager({ config: moduleConfiguration });
manager.subscribe((state) => {
  if (state.status === 'form') render(state.sections, state.values, state.errors);
  if (state.status === 'finished') console.log(state.result?.referenceId);
});
manager.load();
manager.setField('country', 'US'); // loads the US form
manager.submit();

Here moduleConfiguration is the EKYB_CHECKS configuration from your Flow or Workflow. On teardown, unsubscribe and call stop().

See also

Was this page helpful?