Web SDK

Configuration and lifecycle

Configure the modal, background styling, methods, completion, and errors.

Initialization

Call ZippyKycSdk.init() to prepare a session. The modal mounts on document.body and stays hidden until you call open().

Initialize

typescript

import { ZippyKycSdk } from "@zippykyc/web-sdk";

ZippyKycSdk.init({
  inquiryId: "147f10c6-d42c-4c31-9518-a14d582bde6b",
  environment: "staging", // "staging" | "production"
  theme: "light",
  language: "en",
  background: "rgba(255, 255, 255, 0.35)", // optional — panel only
  backgroundBlur: "12px", // optional — or false
  debug: false,
  onComplete: ({ inquiryId, referenceId }) => {
    console.log({ inquiryId, referenceId });
    // Session is torn down. Call init() again for a new inquiry.
  },
  onClose: () => {
    console.log("user dismissed the modal");
    // Session stays alive — call open() to show again.
  },
  onError: ({ code, message }) => {
    console.error(code, message);
  },
});

ZippyKycSdk.open();

Modal lifecycle

The SDK always mounts a full-page modal on document.body.

Session behavior

Name	Type	Description
`init()`	action	Prepares the session; modal stays hidden.
`open()`	action	Shows the modal.
`close()`	action	Calls onClose and hides the modal. The session stays alive — call open() again.
`X / overlay / Escape`	dismiss	Same as close().
`Verification complete`	complete	SDK tears down the session, then calls onComplete. Call init() again for a new inquiry.
`Re-init while alive`	rejected	Throws. Wait for onComplete teardown first.

Options

Initialization options

Name	Type	Required	Description
`inquiryId`	uuid	Required	Invitation / inquiry identifier.
`environment`	staging \| production	Optional	Hosted environment. Defaults to "staging" when omitted.
`theme`	string	Optional	Optional theme forwarded to the KYC experience.
`language`	string	Optional	Optional BCP-47 language tag.
`background`	hex \| rgb() \| rgba()	Optional	Modal panel fill color. Defaults to rgba(255, 255, 255, 0.18). Does not change the page overlay.
`backgroundBlur`	CSS length \| false	Optional	Modal panel blur. Pass false to disable. Defaults to "12px".
`showCloseButton`	boolean	Optional	Shows the X button on the panel. Defaults to true.
`closeOnBackdropClick`	boolean	Optional	Dismisses when the page overlay is clicked. Defaults to true.
`debug`	boolean	Optional	Enables console diagnostics. Keep disabled in production.
`onComplete`	function	Optional	Called after verification completes and the SDK tears down the session.
`onClose`	function	Optional	Called after close() / X / overlay / Escape. Session stays alive.
`onError`	function	Optional	Called for runtime SDK failures.

Panel background

background and backgroundBlur style the modal panel only. The page overlay is a fixed dim and is not customizable.

Accepted background formats

Name	Type	Description
`Hex`	3 / 4 / 6 / 8 digits	#fff, #fff8, #ffffff, #ffffff2e
`rgb() / rgba()`	CSS function	rgb(255, 255, 255) or rgba(255, 255, 255, 0.35)

Example

typescript

ZippyKycSdk.init({
  inquiryId: "...",
  background: "#ffffff2e", // or "rgba(255, 255, 255, 0.35)"
  backgroundBlur: "16px", // or false
});

Methods

Name	Type	Description
`init(options)`	void	Prepares the session (hidden until open()). Re-init only after verification completes.
`open()`	void	Shows the modal. Safe to call again after dismiss.
`close()`	void	Hides the modal only; session stays alive; calls onClose.
`version()`	string	Returns the SDK version string.

Callbacks

Name	Type	Description
`onComplete({ inquiryId?, referenceId? })`	callback	Verification finished; session already torn down.
`onClose()`	callback	User dismissed with close() / X / overlay / Escape; session still alive.
`onError({ code, message })`	callback	Runtime failures such as READY_TIMEOUT or IFRAME_LOAD_ERROR.

Completion payload

typescript

type VerificationCompletePayload = {
  inquiryId?: string;
  referenceId?: string | null;
};

Browser security

Serve the integrating application over HTTPS.
Allow the Zippy KYC iframe origin in frame-src. Contact Zippy for the hosts to allowlist for your environment.
If you load the SDK from a CDN, allow that origin in script-src.
Camera and microphone flows need an appropriate Permissions Policy (the SDK sets a default iframe allow attribute).
Keep SDK debug logging disabled in production.

Framework integrations

Verification screens