# Government Validation Module

<WebSDK2 />

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](doc:web-sdk-2-module-patterns#3-backend-process-modules) and the [form-based pattern](doc: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.

## 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

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

## See also

* [Module Patterns → backend-process](doc:web-sdk-2-module-patterns#3-backend-process-modules)
* [Module Patterns → form-based (OTP sub-loop)](doc:web-sdk-2-module-patterns#1-form-based-modules)
* [Individual Modules](doc:web-sdk-2-individual-modules)