# eKYB Module

<WebSDK2 />

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](doc: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.

## See also

* [Module: eKYC](doc:web-sdk-2-module-ekyc): equivalent for individual identity verification
* [Module: Watchlist for Business](doc:web-sdk-2-module-watchlist-for-business): separate sanctions screening
* [Module Patterns → form-based](doc:web-sdk-2-module-patterns#1-form-based-modules)
* [Individual Modules](doc:web-sdk-2-individual-modules)