# eKYC Module

<WebSDK2 />

The eKYC (electronic Know Your Customer) module collects identity verification data through a configurable form — name, address, phone, email, SSN/tax ID, date of birth, ID numbers, etc. — and submits it to Incode's KYC verification engine. The displayed fields and their data sources (manual entry, document OCR, prior phone/email modules) are dashboard-driven.

> Follows a [form-based pattern](doc:web-sdk-2-module-patterns#1-form-based-modules) variant — dashboard-driven dynamic field schema with optional pre-fill from earlier modules. See the patterns page for the shared lifecycle.

## Tag

`<incode-ekyc>` 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/ekyc';
import '@incodetech/web/ekyc/styles.css';
```

## Properties

| Property   | Type                      | Required | Description                          |
| ---------- | ------------------------- | -------- | ------------------------------------ |
| `config`   | `EkycConfig`              | ❌        | eKYC configuration                   |
| `onFinish` | `() => void`              | ❌        | Called when KYC submission completes |
| `onError`  | `(error: string) => void` | ❌        | Called when an error occurs          |

## Configuration

```typescript
type EkycConfig = {
  flowId?: string;
  verificationFields?: EkycVerificationFields;
  source?: string;
  fieldsCountry?: string;
  enablePhoneRisk?: boolean;
};
```

| Option               | Type                     | Required | Description                                                                                                                                              |
| -------------------- | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `flowId`             | `string`                 | ❌        | Session flow ID; injected by the orchestrator.                                                                                                           |
| `verificationFields` | `EkycVerificationFields` | ❌        | Per-field source map. Each value is `'user_input' \| 'document_scan' \| 'poa_document' \| 'phone_module_input' \| 'email_module_input' \| false` (omit). |
| `source`             | `string`                 | ❌        | Backend-side override for default field source.                                                                                                          |
| `fieldsCountry`      | `string`                 | ❌        | ISO country code; controls country-specific field rendering.                                                                                             |
| `enablePhoneRisk`    | `boolean`                | ❌        | Enable phone-risk subprocess on submit.                                                                                                                  |

The full list of `EkycVerificationFields` keys: `name`, `address`, `phone`, `email`, `SSN`, `taxId`, `nationality`, `'date of birth'`, `dlNumber`, `dlState`, `dlExpireAt`, `last4SSN`, `idNum`, `idNum1`, `gender`, `panNumber`. Each field can be sourced from manual entry, OCR'd ID data, POA document data, or a prior phone/email module.

## State machine

`EkycState` is a discriminated union over `status`:

| Status          | Description                                                                |
| --------------- | -------------------------------------------------------------------------- |
| `loading`       | Fetching field schema and any pre-fill data from prior modules.            |
| `form`          | Rendering the configured form fields; user enters / corrects data.         |
| `submitting`    | Submitting to the eKYC backend.                                            |
| `success`       | Submission accepted.                                                       |
| `finished`      | Terminal.                                                                  |
| `closed`        | User dismissed.                                                            |
| `error`         | Submission or load error.                                                  |
| `misconfigured` | The backend returned no usable field configuration; can't render the form. |

## See also

* [Module: eKYB](doc:web-sdk-2-module-ekyb): equivalent for businesses
* [Module Patterns → form-based](doc:web-sdk-2-module-patterns#1-form-based-modules)
* [Module Patterns → composite](doc:web-sdk-2-module-patterns#5-composite--orchestrator-modules)
* [Individual Modules](doc:web-sdk-2-individual-modules)