Government Validation Module

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.

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.

Availability

This module is headless-only — there is no public <incode-government-validation> web component. Drive it with createGovernmentValidationManager from @incodetech/core/government-validation. Typically invoked from an orchestrated flow.

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

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.
`unknown`	Validation completed with an inconclusive result.
`finished`	Terminal — validation accepted (or auto-skipped on a non-fatal failure).
`error`	Fatal error.

Government Validation Module

Availability

Configuration

State machine

See also