Web SDK

Web SDK overview

Open a template-driven Zippy verification modal in any JavaScript application.

@zippykyc/web-sdk opens the hosted Zippy verification experience in a full-page modal. Your integration provides an inquiry identifier; the inquiry template controls the customer experience.

Installation

npm

bash

npm install @zippykyc/web-sdk

Yarn

bash

yarn add @zippykyc/web-sdk

CDN

html

<script src="https://unpkg.com/@zippykyc/web-sdk/dist/zippykyc-sdk.min.js"></script>
<script>
  ZippyKycSdk.init({
    inquiryId: "147f10c6-d42c-4c31-9518-a14d582bde6b",
    environment: "staging",
  });
  ZippyKycSdk.open();
</script>

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

Quick start

Call init() to prepare the session, then open() when you want to show the modal.

JavaScript

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("Verification complete", { 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();

Template-driven experience

The Web SDK does not define a fixed sequence of screens. Zippy reads the inquiry's pinned template and displays only the configured capabilities and fields.

Name	Type	Description
`Personal information`	conditional	Configured fields determine what appears and which values are required. Email and phone can be disabled, optional, or required.
`Identity document`	conditional	The customer chooses from the document types allowed by the template.
`Selfie`	conditional	Displayed only when the inquiry requires face verification.
`Signature`	conditional	Displayed only when signature collection is configured.
`Completion`	outcome	The hosted experience completes according to the inquiry state and template policy.

Integration lifecycle

Initialize

Call init() to prepare the session. The modal stays hidden.

Open

Call open() to show the modal. Safe again after the user dismisses.

Observe

Handle onClose (dismiss), onComplete (finished), and onError.

Next steps

Framework examples

React, Angular, Vue, Next.js, and vanilla usage.

Configuration

Options, methods, callbacks, and modal styling.

Verification screens

Conditional screens, capture, and browser needs.

Merchant Inquiry API

Framework integrations