📘

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 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](https://developer.incode.com/docs/web-sdk-2-module-patterns#3-backend-process-modules) and the [form-based pattern](https://developer.incode.com/docs/web-sdk-2-module-patterns#1-form-based-modules) — 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.

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

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