Events

The component fires standard DOM CustomEvents; listen with addEventListener. In React the matching props are onReady, onStepChange, onCaptured, onComplete and onError.

Event	When	`detail`
`ready`	The SDK loaded and the flow started	—
`stepchange`	The step changed	`{ step, previous }`
`captured`	A document or face was captured	The captured media
`complete`	The flow finished successfully	Result summary
`error`	An error occurred	Error information

`stepchange`

{
  step: FlowStep;
  previous: FlowStep;
}

type FlowStep =
  | 'idle' | 'select' | 'card-front' | 'card-back'
  | 'hologram' | 'face' | 'results' | 'complete' | 'error';

`captured`

Fired on every capture.

// Document
{
  step: 'card-front' | 'card-back' | 'hologram';
  image: string;   // data URL
  blob: Blob;
  cardType: string;
}

// Face
{
  step: 'face';
  image?: string;
  video?: Blob;
}

`complete`

{
  transactionId: string;
  cardType: string | null;
  includeImages: boolean;
  cardFront?: { cardType: string; hasImage: true };
  cardBack?: { cardType: string; hasImage: true };
  hologram?: { cardType: string; hasImage: true };
  face?: { hasImage: boolean; hasVideo: boolean };
  skipped: { face: boolean; hologram: boolean; cardBack: boolean };
  apiResults: Record<string, unknown>; // Prove ID responses per step
}

Media is left out by default. With include-images="true" the capture fields also carry the images and video.

`error`

{
  code:
    | 'token_error'         // invalid token or session could not start
    | 'card_submit_failed'  // document submission failed
    | 'face_verify_failed'  // face could not be verified
    | 'request_timeout'     // timeout
    | 'flow_error';         // unexpected error
  message: string;
  retryable: boolean;       // true when the user can try again
  step?: FlowStep;
  cause?: unknown;
}

Code	Retryable
`token_error`	No
`card_submit_failed`	Yes
`face_verify_failed`	Yes, while attempts remain
`request_timeout`	Yes
`flow_error`	No

If a document submission fails or times out, the flow stops and the SDK offers the user a Retry option; it never silently moves on. For errors with retryable: false, start a new session for the user.

The package also exports helpers: SDK_ERROR_CODES, isRequestTimeout.