# eKYC Module Documentation

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 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](https://developer.incode.com/docs/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.

## Risk addons

The dashboard-driven module config exposes a `riskAddons` array (`RiskAddon`: `'phoneCheck' | 'advancedPhoneCheck' | 'emailCheck'`). A matching addon renders the corresponding input even when its `checkPhone` / `checkEmail` flag is off:

- `phoneCheck` or `advancedPhoneCheck` renders the phone input.
- `emailCheck` renders the email input.

A module `source` of `RISK_ADDONS_ONLY` runs the eKYC form purely to collect the inputs the configured risk addons need, without a full identity-data check. These values come from the dashboard flow configuration, so most callers pass them through unmodified.

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