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
- The module loads and shows a country field.
- When the user picks a country, the module loads that country's form. Only the country field shows while the new form loads.
- The user fills in the fields and continues. The module validates the form and submits it.
- On success, the module calls
onFinishwith areferenceId.
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
- Module: eKYB: the form-based business verification module
- Module: eKYC Prefill: a similar served, configuration-driven form for individuals
- Module Patterns → form-based
- Individual Modules