eKYC 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 eKYC (electronic Know Your Customer) module collects identity verification data through a configurable form including 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 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.

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

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.

Dashboard field configuration

EkycConfig above is what you set in application code. The dashboard sends its own shape, EkycModuleConfig, which the orchestrator resolves into the rendered form. You do not set it yourself, but it is exported from @incodetech/core/ekyc so you can type a response you inspect.

It configures each verifiable field with a pair of properties:

check<Field> (boolean): whether to verify that field at all.
<field>Source (string): where its value comes from, using the same source names as verificationFields.

For example, checkName plus nameSource, and checkDob plus dobSource. The pairs cover Name, Email, Address, Phone, Ssn, Dob, Nationality, DlNumber, DlState, DlExpireAt, Last4SSN, IdNum, IdNum1, Gender, and PanNumber. A top-level source sets the default for fields with no explicit source, and riskAddons and enablePhoneRisk carry the risk configuration.

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

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.

API methods

Fields come from the dashboard schema, so this module uses one keyed setter rather than a setter per field.

Method	Purpose	Callable when
`load()`	Fetch the field schema and any prefill from earlier modules.	`loading`
`setField(name, value)`	Set one 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`
`submit()`	Submit the form.	`form`
`retry()`	Return to the form after a submission error.	`error`
`skip()`	Skip verification and continue the flow past the failure.	`error`