eKYB Module

Note

This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation here. Contact your Incode Representative for upgrade information and check if you are a candidate for this upgrade.

Full rollout to all clients still TBD.

The eKYB (electronic Know Your Business) module collects business verification data including country, business name, address, and tax ID, plus a list of UBOs (Ultimate Beneficial Owners). It then submits the package to Incode's business verification engine.

Follows a form-based pattern variant with country-aware field schemas and a UBO repeater. See the patterns page for the shared lifecycle.

Tag

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

import '@incodetech/web/ekyb';
import '@incodetech/web/ekyb/styles.css';

Properties

Property	Type	Required	Description
`config`	`EkybConfig`	❌	eKYB configuration
`onFinish`	`() => void`	❌	Called when KYB submission completes
`onError`	`(error: string) => void`	❌	Called when an error occurs

Configuration

type EkybConfig = {
  flowId?: string;
  verificationFields?: string[];
  checkBusinessName?: boolean;
  checkAddress?: boolean;
  checkTaxId?: boolean;
  checkUniqueBeneficialOwner?: boolean;
};

Option	Type	Required	Description
`flowId`	`string`	❌	Session flow ID; injected by the orchestrator.
`verificationFields`	`string[]`	❌	List of fields to verify (used by the backend's KYB checks).
`checkBusinessName`	`boolean`	❌	Run business-name verification.
`checkAddress`	`boolean`	❌	Run address verification.
`checkTaxId`	`boolean`	❌	Run tax-ID verification.
`checkUniqueBeneficialOwner`	`boolean`	❌	Validate that UBOs are unique.

Dashboard field configuration

EkybConfig above is what you set in application code. The dashboard sends its own shape, FlowModuleConfig['EKYB'], which the orchestrator resolves into the rendered form. You do not set it yourself.

It pairs each verifiable field with a source, the same way eKYC does:

check<Field> (boolean) — whether to verify that field at all.
<field>Source ('userInput') — where its value comes from.

The pairs cover business name (checkBusinessName / businessNameSource), tax ID (checkTaxId / taxIdSource), and unique beneficial owner (checkUniqueBeneficialOwner / uniqueBeneficialOwnerSource).

Address breaks the naming pattern. Its source field is address, not addressSource — so checkAddress pairs with address. Reach for the sibling name and you get undefined.

To change which fields a flow verifies, edit the eKYB module in your dashboard rather than passing config in code.

Supported countries

Built-in country support: BR, US, GB, ES, IT, FR, DE, IL, MX, CN, NG, CM, KE. Each country drives a different field schema (which fields are shown, which are required) — the manager looks up the schema from EkybCountry on country change.

State machine

EkybState is a discriminated union over status:

Status	Description
`loading`	Fetching business field schema for the selected country.
`form`	Rendering the form (business fields + UBO repeater).
`submitting`	Submitting the package to the eKYB backend.
`success`	Submission accepted.
`finished`	Terminal.
`closed`	User dismissed.
`error`	Submission or load error.

API methods

Business fields come from the dashboard schema, so this module uses one keyed setter. It also owns the UBO (ultimate beneficial owner) repeater.

Method	Purpose	Callable when
`load()`	Fetch the business field schema for the selected country.	`loading`
`setCountry(country)`	Set the country. Changing it reloads the schema.	`form`
`setField(name, value)`	Set one business field, keyed by its name in the schema.	`form`
`validateField(name)`	Validate one field. Call it on blur.	`form`
`searchAddress(query)`	Fetch address autocomplete suggestions. Debounce it yourself.	`form`
`selectAddress(suggestion)`	Apply one suggestion from `searchAddress`. A street-level result is required.	`form`
`addUbo()`	Append a UBO entry. Caps at eight.	`form`
`removeUbo(index)`	Remove the UBO entry at that index.	`form`
`setUboField(index, field, value)`	Set `'name'` or `'surname'` on one UBO entry.	`form`
`submit()`	Submit the package.	`form`
`retry()`	Return to the form after a submission error.	`error`