📘  
This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation [here](https://developer.incode.com/docs/web-sdk-reference). 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 — country, business name, address, tax ID — plus a list of UBOs (Ultimate Beneficial Owners). Submits the package to Incode's business verification engine.

Follows a [form-based pattern](https://developer.incode.com/docs/web-sdk-2-module-patterns#1-form-based-modules) 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.

```ts
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

```typescript
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. |

## 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. |

UBOs are managed via `ADD_UBO`, `REMOVE_UBO`, and `SET_UBO_FIELD` events on the manager.