@zippykyc/web-sdk

Embeddable TypeScript SDK that mounts the hosted Zippy KYC experience in an iframe and communicates with it over a versioned postMessage protocol.

Install

npm install @zippykyc/web-sdk
# or
yarn add @zippykyc/web-sdk

Script tag (CDN)

<script src="https://unpkg.com/@zippykyc/web-sdk/dist/zippykyc-sdk.min.js"></script>
<script>
  ZippyKycSdk.init({
    inquiryId: "897a5064-9570-4216-8bb4-c74b2fd6295e",
    environment: "staging",
  });
  ZippyKycSdk.open();
</script>

Also available via jsDelivr: https://cdn.jsdelivr.net/npm/@zippykyc/web-sdk/dist/zippykyc-sdk.min.js.

Quick start

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

ZippyKycSdk.init({
  inquiryId: "897a5064-9570-4216-8bb4-c74b2fd6295e",
  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("done", { 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);
  },
});

// Modal stays hidden until you open it
ZippyKycSdk.open();

Modal lifecycle

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

| Action | Result | |---|---| | init() | Prepares session; modal stays hidden | | open() | Shows the modal | | close() | Calls onClose, hides modal; session stays alive → open() again | | X / overlay click / Escape | Same as close() | | Verification complete | SDK tears down session, then calls onComplete → init() allowed again | | Re-init() while session alive | Rejected (throws) |

Panel background (background / backgroundBlur)

These options style the modal panel only. They do not change the page overlay.

| Option | Default | Description | |---|---|---| | background | rgba(255, 255, 255, 0.18) | Panel fill color | | backgroundBlur | "12px" | Panel frosted blur. Pass false to disable |

Page overlay is a fixed dim and is not customizable.

Accepted background formats

| Format | Examples | |---|---| | Hex (3 / 4 / 6 / 8 digits) | #fff, #fff8, #ffffff, #ffffff2e | | rgb() / rgba() | rgb(255, 255, 255), rgba(255, 255, 255, 0.35) |

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

Environments

Use environment: "staging" (default) or environment: "production". The SDK selects the hosted KYC host automatically.

init options

| Option | Required | Type | Default | Notes | |---|---|---|---|---| | inquiryId | Yes | UUID string | — | Invitation / inquiry id | | environment | No | "staging" | "production" | "staging" | Hosted environment | | theme | No | string | — | Forwarded to the KYC experience | | language | No | string | — | BCP-47 language tag | | background | No | hex or rgb() / rgba() | rgba(255, 255, 255, 0.18) | Modal panel only | | backgroundBlur | No | CSS length | false | "12px" | Modal panel only | | showCloseButton | No | boolean | true | X button on panel | | closeOnBackdropClick | No | boolean | true | Dismiss on overlay click | | debug | No | boolean | false | Console diagnostics | | onComplete | No | function | — | After verification + teardown | | onClose | No | function | — | After user dismiss (session alive) | | onError | No | function | — | Runtime errors |

Invalid options are rejected with a console error and an on-page banner; the iframe is not mounted until options are valid.

Callbacks

| Callback | When | |---|---| | onComplete({ inquiryId?, referenceId? }) | Verification finished; session already torn down | | onClose() | User dismissed with close() / X / overlay / Escape; session still alive | | onError({ code, message }) | Runtime failures such as READY_TIMEOUT, IFRAME_LOAD_ERROR |

API

| Method | Description | |---|---| | init(options) | Prepare the session (hidden until open()). Re-init only after complete | | open() | Show the modal (safe after dismiss) | | close() | Hide the modal only; session stays alive; calls onClose | | version() | SDK version string |

CSP notes for host apps

Allow the Zippy KYC iframe origin in frame-src (and the CDN origin in script-src if using the script tag). Contact Zippy for the exact hosts to allowlist for your environment.

Camera / mic flows also need appropriate Permissions-Policy / feature allow lists (the SDK sets a default iframe allow attribute).

License

MIT — see LICENSE.