Government Validation 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 Government Validation module submits the user's identity data (typically post-ID-capture) to a government registry for verification. Multiple validation types can run simultaneously (facial, data, address) and OTP confirmation may be required for some country/regulator combinations.

The same module handles two flow variants that share one manager, state machine, and UI: GOVT_VALIDATION_PROVISIONING (the general government-registry check) and INE_VALIDATION (the Mexico INE check). The Mexico INE variant is the one that drives the OTP sub-loop (awaitingOtp / verifyingOtp). Both variants are configured from the dashboard flow, so most callers pass the config through unmodified.

Follows a hybrid of the backend-process pattern and the form-based pattern — backend-driven processing with an optional OTP sub-loop. See the patterns page for the shared lifecycle.

Tag

<incode-government-validation> is a standard Web Component. Importing the UI subpath registers the custom element; importing the CSS applies the module's styles.

import '@incodetech/web/government-validation';
import '@incodetech/web/government-validation/styles.css';

For headless (no pre-built UI) control, drive it with createGovernmentValidationManager from @incodetech/core/government-validation. This module is typically invoked from an orchestrated flow rather than mounted standalone.

Configuration

type GovernmentValidationConfig = {
  validationCountries: string[];
  facialValidation: boolean;
  dataValidation: boolean;
  faceAndDataValidation: boolean;
  addressValidation: boolean;
  backgroundExecution: boolean;
  faceMatchOverrideDataScore: boolean;
  useCroppedIdFacePhoto: boolean;
  maxOtpAttempts?: number;
};

Option	Type	Required	Description
`validationCountries`	`string[]`	✅	ISO country codes the backend should run against.
`facialValidation`	`boolean`	✅	Run facial validation (selfie ↔ government photo).
`dataValidation`	`boolean`	✅	Run data validation (name, DOB, etc.).
`faceAndDataValidation`	`boolean`	✅	Combined face + data check.
`addressValidation`	`boolean`	✅	Run address validation.
`backgroundExecution`	`boolean`	✅	When `true`, run silently without UI; advance via `onFinish`.
`faceMatchOverrideDataScore`	`boolean`	✅	Advanced: face-match score overrides data-score for the final decision.
`useCroppedIdFacePhoto`	`boolean`	✅	Use the cropped ID face photo (vs. full ID image).
`maxOtpAttempts`	`number`	❌	Max OTP attempts when OTP is required. Default `3`.

INE validation options

These options apply to the Mexican INE check. Set them on the module's dashboard configuration rather than in application code:

Option	Type	Required	Description
`alternativeFacialValidation`	`boolean`	❌	Use the alternative facial-validation route for INE.
`fallbackEnabled`	`boolean`	❌	Allow the backend to fall back to another validation route when the primary one is unavailable.
`scrapingMethod`	`boolean`	❌	Select the scraping-based INE validation route.
`scrapingV2`	`boolean`	❌	Select version 2 of the scraping route.
`scrapingV3`	`boolean`	❌	Select version 3 of the scraping route.
`failUnsupportedId`	`boolean`	❌	Fail the module when the submitted document is not supported, instead of advancing.

These fields come from the dashboard's flow configuration. Most callers pass them through unmodified from the orchestrator's state.config.

State machine

GovernmentValidationState is a discriminated union over status:

Status	Description
`idle`	Initial state.
`loading`	Loading configuration / starting validation.
`processing`	Backend validation in progress.
`awaitingOtp`	The chosen validation requires the user to confirm an OTP.
`verifyingOtp`	Verifying the submitted OTP.
`displaySuccess`	Validation succeeded; the success result shows before the module finishes.
`unknown`	Validation completed with an inconclusive result.
`finished`	Terminal — validation accepted (or auto-skipped on a non-fatal failure).
`error`	Fatal error.

API methods

Beyond the shared backend-process set, this module owns the OTP step:

Method	Purpose	Callable when
`setOtpCode(code)`	Hold the code the user is typing.	`awaitingOtp`
`validateOtp()`	Submit the held code for verification.	`awaitingOtp`
`retry()`	Retry after a failed validation.	`error`

Government Validation Module

Tag

Configuration

INE validation options

State machine

API methods

See also