eKYC Module

eKYC Module Documentation

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 — 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'
`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.