@myazahq/kyc-sdk-react-native 2.3.0 → 2.5.0

package/src/store/state.ts

@@ -9,7 +9,7 @@ import type { FlashHole } from '../components/flashHoleGeometry';
 
 import type { StoreApi } from 'zustand/vanilla';
 
-import type { KYCApi, KeyPersonInvite } from '../services/api';
+import type { BusinessCompanyRecord, KYCApi, KeyPersonInvite, RegistryOfficer } from '../services/api';
 import type { IdType, KYCStep, ResolvedKYCConfig } from '../types/config';
 import type { PoaDocumentType } from '../types/workflow';
 import type { ApplicantRole } from '../types/business';
@@ -35,7 +35,7 @@ export interface KYCMediaIds {
 
 export interface KYCSubmissionResult {
   verificationId: string;
-  status: 'pending';
+  status: 'processing';
 }
 
 export type DocumentScanPhase = 'front' | 'back' | 'complete';
@@ -48,12 +48,69 @@ export interface BusinessState {
   product: string | null;
   registrationNumber: string;
   registrationName: string;
+  /** Dev/sandbox only: pins the canned outcome served instead of calling the
+   *  register. Sent as metadata.sandboxOutcome; production ignores it. */
+  sandboxOutcome: string;
+  /** ISO 3166-2 registry region, for the four countries whose register is
+   *  split by state or emirate. Empty for everywhere else. Rides the search
+   *  and the selection-time check; the submission relies on the prepaid
+   *  record, mirroring the web SDK. */
+  subdivisionCode: string;
   /** Where key-people invite links are emailed. */
   contactEmail: string;
   address: string;
   email: string;
   phone: string;
   website: string;
+  /** Registry facts the applicant states; submitted as their own answer. */
+  dateOfIncorporation: string;
+  taxId: string;
+  vatNumber: string;
+  companyType: string;
+  natureOfBusiness: string;
+}
+
+/**
+ * The registry check run when the applicant confirms their company.
+ *
+ * `skipped` and `limit_reached` are normal outcomes, not failures: the
+ * organisation could not be charged (or this application has spent its lookup
+ * budget), so the flow carries on and the check happens at submission instead.
+ * Mirrors the web SDK's BusinessCheckState — keep the two in lockstep.
+ */
+export interface BusinessCheckState {
+  status: 'idle' | 'checking' | 'found' | 'not_found' | 'skipped' | 'unavailable' | 'limit_reached';
+  /** What the register holds, when it answered. */
+  company: BusinessCompanyRecord | null;
+  /** The officers on file — what makes the key-people question a confirmation. */
+  officers: RegistryOfficer[];
+  /** Which company was checked (normalised), so a changed number re-runs it. */
+  checkedNumber: string | null;
+  /**
+   * Which form fields the REGISTER filled, as opposed to the applicant.
+   *
+   * Kept so that changing which company this is can clear exactly those and
+   * nothing else. Without it, switching company left the previous register's
+   * address and email sitting in the form under the new company's name — and
+   * because the prefill only writes into empty fields, those leftovers also
+   * blocked the new register's real values from ever landing.
+   */
+  prefilled: (keyof BusinessState)[];
+}
+
+export const EMPTY_BUSINESS_CHECK: BusinessCheckState = {
+  status: 'idle',
+  company: null,
+  officers: [],
+  checkedNumber: null,
+  prefilled: [],
+};
+
+/** What `checkBusiness` resolves with. Only a definitive "not on the register"
+ *  stops the flow; the company record is handed back for the prefill. */
+export interface BusinessCheckResult {
+  canContinue: boolean;
+  company: BusinessCompanyRecord | null;
 }
 
 /** One uploaded supporting document. */
@@ -83,6 +140,13 @@ export interface BusinessApplicationState {
    * one screening, no duplicate invite.
    */
   applicantKeyPersonIndex: number | null;
+  /**
+   * The applicant attests that no natural person qualifies as a UBO (public
+   * share structures, complex trusts, nominee arrangements) - the FATF
+   * fallback. An attestation the server records and the org can branch on,
+   * never a verdict; the registry lookup still says what it says.
+   */
+  uboUnidentifiable: boolean;
 }
 
 export const EMPTY_BUSINESS_APPLICATION: BusinessApplicationState = {
@@ -91,6 +155,7 @@ export const EMPTY_BUSINESS_APPLICATION: BusinessApplicationState = {
   applicantRole: null,
   applicantName: '',
   applicantKeyPersonIndex: null,
+  uboUnidentifiable: false,
 };
 
 export const EMPTY_BUSINESS: BusinessState = {
@@ -98,11 +163,18 @@ export const EMPTY_BUSINESS: BusinessState = {
   product: null,
   registrationNumber: '',
   registrationName: '',
+  sandboxOutcome: '',
+  subdivisionCode: '',
   contactEmail: '',
   address: '',
   email: '',
   phone: '',
   website: '',
+  dateOfIncorporation: '',
+  taxId: '',
+  vatNumber: '',
+  companyType: '',
+  natureOfBusiness: '',
 };
 
 export interface ContactState {
@@ -112,6 +184,16 @@ export interface ContactState {
   emailToken?: string;
   /** Single-use proof from a passed phone check. */
   phoneToken?: string;
+  /**
+   * Channels whose proof the SERVER refused at submit (422
+   * contact_verification_required). Proofs are single-use and expire ~30
+   * minutes after the OTP check, but they ride session progress and are
+   * restored on resume — so a resumed attempt can carry a dead proof while
+   * the step still shows "verified". This routes the person back to
+   * re-verify instead of a retry that resubmits the same dead token forever;
+   * setContactVerified clears its channel.
+   */
+  expired?: Array<'email' | 'phone'>;
 }
 
 /** Document-capture sub-phase — drives the sheet header title/description. */
@@ -120,11 +202,47 @@ export type DocumentCapturePhase = 'front' | 'front-preview' | 'back' | 'review'
 /** The mediaIds keys settable via `setMediaId`. */
 export type MediaIdKey = keyof KYCMediaIds;
 
+/** One committed multi-ID check. `documentFront/Back` are mediaIds; the
+ *  `*Image` fields are LOCAL previews and never reach the wire. */
+export interface MultiIdSlot {
+  idType: IdType;
+  idNumber?: string;
+  documentFront?: string;
+  documentBack?: string;
+  /** Each check records its OWN document capture. The row's flat
+   *  documentFrontVideo column holds one, so a multi-ID run keeps them per
+   *  check or loses all but one. */
+  documentFrontVideo?: string;
+  documentBackVideo?: string;
+  /** This check's own chip read. The chip belongs to a PARTICULAR document, so
+   *  sending it top-level attributed it to the primary check — which is how a
+   *  passport's chip read was dropped for being submitted alongside a BVN. */
+  chipData?: EmrtdReadResult | null;
+  documentFrontImage?: string;
+  documentBackImage?: string;
+}
+
 export interface KycState {
   config: ResolvedKYCConfig;
   api: KYCApi;
 
   currentStep: KYCStep;
+  /**
+   * The attempt SESSION this run is recorded under (`/session/start`). Null
+   * when minting failed or preview — verifying is never conditional on it. It
+   * rides the /verify body so the verification adopts the session's id, and it
+   * is what the registry check at selection anchors its charge on.
+   */
+  sessionId: string | null;
+  /** The session's own hosted web page (see SessionStartResponse.url). */
+  sessionUrl: string | null;
+  /**
+   * What the register said about the company the applicant identified — the
+   * paid check run at SELECTION (`/business/select`), so the officer list is
+   * already here by the time the key-people step asks for it. `officers` is
+   * the prefill's input; `checkedNumber` stops a re-check of the same company.
+   */
+  businessCheck: BusinessCheckState;
   /**
    * The country picked on the multi-region country-select step. Null on a
    * single-country flow, where `config.country` is the answer.
@@ -132,6 +250,22 @@ export interface KycState {
   selectedCountry: string | null;
   selectedIdType: IdType | null;
   idNumber: string | null;
+  /**
+   * Multi-ID: which check the applicant is on (0-based), and the ones already
+   * committed. A committed slot keeps its LOCAL preview images as well as its
+   * mediaIds, so stepping back into it restores what was captured rather than
+   * asking for a document that is still perfectly good.
+   */
+  multiIdSlotIndex: number;
+  multiIdSlots: MultiIdSlot[];
+  /**
+   * Capture previews handed back when stepping BACK into a committed slot.
+   *
+   * RN keeps document previews in the capture screen's own state, so a restored
+   * slot has to hand them somewhere the remounting screen can read them. Null
+   * on the forward journey.
+   */
+  multiIdRestored: { front?: string; back?: string } | null;
   mediaIds: KYCMediaIds;
   submissionResult: KYCSubmissionResult | null;
   serverConfig: ServerConfigState;
@@ -219,13 +353,32 @@ export interface KycState {
   setCountry: (country: string) => void;
   setIdType: (idType: IdType) => void;
   setIdNumber: (idNumber: string) => void;
+  /** Commit the current slot's evidence and move to the next check. The
+   *  previews come from the capture screen, which owns them. */
+  commitMultiIdSlot: (nextStep: KYCStep, previews?: { front?: string; back?: string }) => void;
+  /** Step BACK into the previous slot, restoring what it captured. */
+  uncommitMultiIdSlot: (step: KYCStep) => void;
   setMediaId: (key: MediaIdKey, mediaId: string) => void;
   setDocumentMediaId: (mediaId: string, side: 'front' | 'back') => void;
   setQuestionnaireAnswer: (key: string, value: QuestionnaireAnswerValue | undefined) => void;
   setContactVerified: (channel: 'email' | 'phone', destination: string, token: string) => void;
   setContactDestination: (channel: 'email' | 'phone', destination: string) => void;
+  /** The server refused these channels' proofs at submit — drop the tokens and
+   *  flag the channels so their steps re-verify then resubmit. */
+  clearContactProofs: (channels: Array<'email' | 'phone'>) => void;
   setBusinessField: <K extends keyof BusinessState>(key: K, value: BusinessState[K]) => void;
+  /** Writes the register's answers into empty fields + records which ones it
+   *  filled, in one set — so a company change can clear exactly those. */
+  applyBusinessPrefill: (
+    patch: Partial<BusinessState>,
+    prefilled: (keyof BusinessState)[],
+  ) => void;
+  setSessionId: (sessionId: string, sessionUrl?: string | null) => void;
+  /** Run the paid registry check for the typed company. Never blocks the flow. */
+  checkBusiness: () => Promise<BusinessCheckResult>;
   setKeyPeople: (rows: KeyPersonEntry[]) => void;
+  /** The UBO-exemption attestation (FATF fallback) — see BusinessApplicationState. */
+  setUboUnidentifiable: (checked: boolean) => void;
   setBusinessDocument: (doc: BusinessDocumentUpload) => void;
   removeBusinessDocument: (type: string) => void;
   setApplicant: (role: ApplicantRole, name: string, keyPersonIndex?: number | null) => void;

package/src/store/submit.ts

@@ -15,12 +15,39 @@
 import { collectDeviceMetadata } from '../services/deviceMetadata';
 import { generateRequestId } from '../utils/uuid';
 import { hasActiveQuestionnaire, questionnairePayload } from '../config/questionnaire';
+import { multiIdWireSlots } from '../lib/multi-id';
 import { isBusinessFlow } from '../config/business';
 import { businessSubmission, effectiveCountry } from './derive';
 import type { ClientFingerprint } from '../services/fingerprint';
 import type { VerifyRequest } from '../services/api';
 import type { KycState } from './state';
 
+/** The chip payload as the wire wants it. One builder, so a slot's chip and a
+ *  single-ID run's are byte-identical to the server. */
+export function nfcPayload(
+  chip: NonNullable<KycState['chipData']>,
+): NonNullable<VerifyRequest['nfc']> {
+  return {
+    dg1: chip.dg1,
+    ...(chip.sod ? { sod: chip.sod } : {}),
+    ...(chip.dg2 ? { dg2: chip.dg2 } : {}),
+    ...(chip.dg7 ? { dg7: chip.dg7 } : {}),
+    ...(chip.dg11 ? { dg11: chip.dg11 } : {}),
+    ...(chip.dg12 ? { dg12: chip.dg12 } : {}),
+    ...(chip.dg15 ? { dg15: chip.dg15 } : {}),
+    ...(chip.aaSignature ? { aaSignature: chip.aaSignature } : {}),
+    ...(chip.aaChallengeId ? { aaChallengeId: chip.aaChallengeId } : {}),
+    chipAuth: chip.chipAuth,
+    // The PACE diagnostic. Read on every session and, until now, dropped here:
+    // every RN chip read reached the server with paceOutcome null, so the one
+    // question the field exists to answer — did this chip decline PACE, or did
+    // ours fail? — was unanswerable for the whole install base. Flutter has
+    // always sent it.
+    ...(chip.paceOutcome ? { paceOutcome: chip.paceOutcome } : {}),
+    ...(chip.paceDetail ? { paceDetail: chip.paceDetail } : {}),
+  };
+}
+
 export function buildVerifyRequest(
   state: KycState,
   fingerprint: ClientFingerprint | undefined,
@@ -30,15 +57,38 @@ export function buildVerifyRequest(
   // capture media at all.
   const business = isBusinessFlow(state.config) ? businessSubmission(state) : null;
 
+  // Multi-ID: every check was committed as a slot, and the whole run submits as
+  // ONE verification the server judges by the workflow's pass policy. The FIRST
+  // slot fills the single-ID fields, so anything reading a verification's own
+  // idType/idNumber keeps one meaning.
+  const multiSlots = !business && state.multiIdSlots.length >= 2 ? state.multiIdSlots : null;
+  const primary = multiSlots?.[0];
+
   return {
   country: business ? business.country : effectiveCountry(state),
-  idType: business ? business.product : (state.selectedIdType ?? ''),
-  idNumber: business ? undefined : (state.idNumber ?? undefined),
+  idType: business ? business.product : (primary?.idType ?? state.selectedIdType ?? ''),
+  idNumber: business ? undefined : (primary?.idNumber ?? state.idNumber ?? undefined),
+  ...(multiSlots
+    ? {
+        idChecks: multiIdWireSlots(multiSlots).map((wire, i) => {
+          const chip = multiSlots[i]?.chipData;
+          return chip ? { ...wire, nfc: nfcPayload(chip) } : wire;
+        }),
+      }
+    : {}),
   ...(business ? { business: business.payload } : {}),
   // The org's user reference (becomes Entity.externalUserId at the KYC seam).
   ...(state.config.userId ? { userId: state.config.userId } : {}),
   userData: business ? undefined : state.config.userData,
-  mediaIds: business ? {} : state.mediaIds,
+  // Multi-ID: the slot documents ride idChecks; only the RUN-level media (the
+  // one selfie and its video) sit at the top level. Sending a slot's document
+  // here too would file the last ID's capture as though it were the
+  // verification's own.
+  mediaIds: business
+    ? {}
+    : multiSlots
+      ? { ...state.mediaIds, documentFront: undefined, documentBack: undefined }
+      : state.mediaIds,
   ...(state.config.workflowId ? { workflowId: state.config.workflowId } : {}),
   ...(state.poaDocumentType ? { proofOfAddressType: state.poaDocumentType } : {}),
   ...(state.contact.emailToken || state.contact.phoneToken
@@ -60,16 +110,9 @@ export function buildVerifyRequest(
   // Omitted entirely when absent rather than sent empty: the server treats a
   // present-but-hollow block as a failed read, which is not the same as a
   // document whose chip was never scanned.
-  ...(state.chipData
-    ? {
-        nfc: {
-          dg1: state.chipData.dg1,
-          ...(state.chipData.sod ? { sod: state.chipData.sod } : {}),
-          ...(state.chipData.dg2 ? { dg2: state.chipData.dg2 } : {}),
-          chipAuth: state.chipData.chipAuth,
-        },
-      }
-    : {}),
+  // Multi-ID: the chip rides its OWN check (above) — a top-level payload could
+  // only ever be attributed to the primary one.
+  ...(!multiSlots && state.chipData ? { nfc: nfcPayload(state.chipData) } : {}),
   // Only sent when the flow actually asked — an inactive questionnaire
   // must not put an empty object on the verification record.
   ...(hasActiveQuestionnaire(state.config.questionnaire)
@@ -80,12 +123,19 @@ export function buildVerifyRequest(
         ),
       }
     : {}),
+  // The attempt session this run happened under: the verification adopts its
+  // id, and any registry check paid at selection is not paid again at submit.
+  ...(state.sessionId ? { sessionId: state.sessionId } : {}),
   // `metadata` is free-form passthrough. The SDK-owned keys (`requestId` —
   // the server's idempotency key — and `device`) are written AFTER the
   // caller's metadata so consumer keys can never clobber them. The user
   // reference is the top-level `userId` above. Identical on web + Flutter.
   metadata: {
     ...(state.config.metadata ?? {}),
+    // Ignored by production, so it is safe to send whenever it is set.
+    ...(business && state.business.sandboxOutcome
+      ? { sandboxOutcome: state.business.sandboxOutcome }
+      : {}),
     requestId: generateRequestId(),
     device: {
       ...(collectDeviceMetadata() as unknown as Record<string, unknown>),

package/src/store/submitApplicant.ts

@@ -14,6 +14,7 @@ import { collectDeviceMetadata } from '../services/deviceMetadata';
 import { generateRequestId } from '../utils/uuid';
 import { splitFullName } from '../config/keyPeople';
 import { effectiveCountry } from './derive';
+import { nfcPayload } from './submit';
 import type { ClientFingerprint } from '../services/fingerprint';
 import type { VerifyRequest } from '../services/api';
 import type { KycState } from './state';
@@ -53,17 +54,10 @@ export function buildApplicantVerifyRequest(
     ...(userData ? { userData } : {}),
     mediaIds: state.mediaIds,
     // The chip read, when the leg ran the NFC step (an overlaid applicant
-    // workflow can enable it). Same block as the individual flow's builder.
-    ...(state.chipData
-      ? {
-          nfc: {
-            dg1: state.chipData.dg1,
-            ...(state.chipData.sod ? { sod: state.chipData.sod } : {}),
-            ...(state.chipData.dg2 ? { dg2: state.chipData.dg2 } : {}),
-            chipAuth: state.chipData.chipAuth,
-          },
-        }
-      : {}),
+    // workflow can enable it). Built by the SHARED builder, not a second copy
+    // of the block: a hand-rolled twin drifts silently, and the applicant's
+    // chip must reach the server in the same shape as everyone else's.
+    ...(state.chipData ? { nfc: nfcPayload(state.chipData) } : {}),
     // NO top-level `userId` here on purpose: the server prefers it over
     // metadata.userId, so sending the org's own user ref would sever the
     // KeyPerson link this submission exists to make.

package/src/types/business.ts

@@ -17,8 +17,21 @@ export type KeyPersonRole = 'director' | 'beneficial_owner' | 'signatory' | 'sha
  *  plus 'authorized_representative' (someone filing on the company's behalf). */
 export type ApplicantRole = KeyPersonRole | 'authorized_representative';
 
-/** Supporting-document kinds a KYB workflow can request from the applicant. */
-export const COMPANY_INFO_FIELDS = ['address', 'email', 'phone', 'website'] as const;
+/** Company-profile fields a KYB workflow can ask for. The last five are
+ *  registry facts the applicant STATES (asked as their own answer rather than
+ *  filled from the register, because where the two differ that is the
+ *  finding). Mirrors the web SDK's CompanyInfoField exactly. */
+export const COMPANY_INFO_FIELDS = [
+  'address',
+  'email',
+  'phone',
+  'website',
+  'dateOfIncorporation',
+  'taxId',
+  'vatNumber',
+  'companyType',
+  'natureOfBusiness',
+] as const;
 export type CompanyInfoField = (typeof COMPANY_INFO_FIELDS)[number];
 export type CompanyInfoMode = 'off' | 'optional' | 'required';
 
@@ -55,12 +68,20 @@ export interface WorkflowKeyPeopleConfig {
   requirement?: 'all_in_scope' | 'ubos_only' | 'advisory';
   /** Per-role verification depth overrides (win over `level`). */
   perRole?: Partial<Record<KeyPersonRole, KeyPeopleLevel>>;
+  /** Emails are mandatory for the roles that are sent a verification link. */
+  requireEmail?: boolean;
+  /** Explicit override of WHICH roles must carry an email. */
+  requireEmailRoles?: KeyPersonRole[];
   /** Invite distribution for full-KYC people. */
   invite?: {
     channel?: string;
     /** The KYC workflow the per-person invite links run through. */
     workflowId?: string;
   };
+  /** Nested KYB: a corporate shareholder is invited into its OWN business
+   *  application (the server mints the link; the SDK only tells the applicant
+   *  the truth about what happens to a company they list). */
+  corporateKyb?: { enabled?: boolean; workflowId?: string };
 }
 
 /**

package/src/types/config.ts

@@ -1,3 +1,4 @@
+import type { ResubmitConfig } from '../lib/resubmit';
 // ---------------------------------------------------------------------------
 // The SDK's public configuration.
 //
@@ -23,6 +24,7 @@ import type {
   ProofOfAddressConfig,
   QuestionnaireConfig,
   WorkflowCountry,
+  MultiIdConfig,
 } from './workflow';
 
 export type * from './workflow';
@@ -62,7 +64,7 @@ export type KYCStep =
 // ---------------------------------------------------------------------------
 
 /** How flow progress is drawn — see {@link MyazaKYCConfig.progressStyle}. */
-export type ProgressStyle = 'steps' | 'bar';
+export type ProgressStyle = 'steps' | 'bar' | 'none';
 
 export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
   /**
@@ -155,6 +157,12 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
    * reflection flash, or both. Workflow-driven.
    */
   livenessMode?: LivenessMode;
+  /**
+   * KYB success screen: after submitting with key people still to verify,
+   * tapping Done offers the session's own web page so the applicant can reach
+   * the invite links again after the app closes. Default true.
+   */
+  keyPeopleLinkRecovery?: boolean;
 
   /** Colours in the flash sequence (2–5, default 4). Flash modes only. */
   flashSequenceLength?: number;
@@ -175,6 +183,10 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
    */
   countries?: WorkflowCountry[];
 
+  /** Multi-ID policy: several ID checks in one run, judged by a pass policy.
+   *  KYC only — publish rejects it on a KYB workflow. */
+  multiId?: MultiIdConfig;
+
   /** Email OTP possession check, right after consent. */
   emailVerification?: EmailVerificationConfig;
 
@@ -187,6 +199,15 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
   /** Compliance declarations asked just before submission. */
   questionnaire?: QuestionnaireConfig;
 
+  /**
+   * A reviewer sent this attempt back to redo specific steps.
+   *
+   * Never set by a consumer and never part of a published workflow — it is
+   * stamped onto ONE session's config snapshot when somebody clicks "Send back".
+   * Absent means the ordinary full flow.
+   */
+  resubmit?: ResubmitConfig;
+
   /** eMRTD chip read for chip-capable documents. */
   nfc?: NfcConfig;
 
@@ -215,8 +236,13 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
    *   • `'bar'` — a single thin bar pinned to the bottom edge of the header.
    *     Quieter, and unaffected by step count, so it suits long flows and hosts
    *     who would rather the chrome said less.
+   *   • `'none'` — no progress in the header at all. For hosts whose own
+   *     surface already communicates progress, or short flows where a
+   *     step count is more noise than reassurance. The header keeps its
+   *     brand row and controls; only the progress element is dropped.
    *
-   * Both convey the same fraction; the choice is how much room it takes.
+   * `'steps'` and `'bar'` convey the same fraction; the choice is how much room
+   * it takes. `'none'` opts out of conveying it here.
    */
   progressStyle?: ProgressStyle;
 
@@ -250,7 +276,7 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
   onStepChange?: (step: KYCStep) => void;
   /**
    * Fires immediately after the user submits. The submission is always
-   * status: 'pending' — results arrive async via webhook.
+   * status: 'processing' — results arrive async via webhook.
    */
   onSubmit?: (submission: KYCSubmission) => void;
   onClose?: () => void;

package/src/types/verification.ts

@@ -4,7 +4,7 @@
 
 export interface KYCSubmission {
   verificationId: string;
-  status: 'pending';
+  status: 'processing';
   metadata: Record<string, string>;
   submittedAt: string;
 }

package/src/types/workflow.ts

@@ -141,11 +141,26 @@ export interface WorkflowCountry {
   idTypes?: string[];
   /** Per-ID validation toggles — restrict-only; they never widen a grant. */
   idOptions?: Record<string, WorkflowIdOption>;
+  /** Multi-ID: which IDs THIS country offers for each verification in the run.
+   *  A pinned slot keeps its list; an absent entry offers everything. */
+  multiIdSlots?: Array<{ idTypes?: string[] }>;
   govDbCheck?: boolean;
   documentIntelligence?: boolean;
 }
 
 // ── Liveness ────────────────────────────────────────────────────────────────
 
+/**
+ * Multi-ID: several ID checks in ONE run, one selfie, one verification. The
+ * POLICY is workflow-level; WHICH IDs each verification offers is per country
+ * (`WorkflowCountry.multiIdSlots`), so multi-region flows work.
+ */
+export interface MultiIdConfig {
+  /** How many IDs the applicant completes (2–3). */
+  count: number;
+  /** How many must pass for the verification to be VERIFIED. */
+  minPassed: number;
+}
+
 /** Gestures (default), screen-reflection flash, or both. */
 export type LivenessMode = 'gestures' | 'flash' | 'both';