@noviuz/kyc-js

The Noviuz Hosted KYC partner SDK. Framework-agnostic, tiny, ships via NPM (ESM/CJS) and CDN (IIFE). It starts the hosted flow with a server-minted sessionId, passes only non-sensitive context, and surfaces only the authorized result (as a notification — reconcile it server-side before acting).

import { NoviuzKyc } from '@noviuz/kyc-js';

// sessionId comes from YOUR server's mint endpoint — see @noviuz/kyc-server. The browser never
// mints a production session.
NoviuzKyc.open({
  sessionId,
  theme: 'auto',
  onSuccess: (result) => reconcileOnYourServer(result.sessionId), // notification, not a decision
  onError: (error) => console.error(error.code, error.message),
});

CDN:

<script
  src="https://cdn.noviuz.com/kyc/v2/noviuz-kyc.<hash>.js"
  integrity="sha384-<sha384-from-manifest>"
  crossorigin="anonymous"
></script>
<script>NoviuzKyc.open({ sessionId: '<server-minted-session-id>', onSuccess: (r) => console.log(r.status) })</script>

API

| Method | Mode | Returns | | --- | --- | --- | | NoviuzKyc.open(config) | modal overlay | NoviuzKycSession | | NoviuzKyc.mount(container, config) | inline iframe | NoviuzKycSession | | NoviuzKyc.redirect(config) | top-level redirect (needs returnUrl); no callbacks fire in this mode | void | | NoviuzKyc.popup(config) | popup window | NoviuzKycSession | | NoviuzKyc.parseRedirectNotification(search?) | read the non-authoritative notification on the return page | RedirectNotificationV2 \| null |

NoviuzKycSession: .on(event, cb), .off(...), .close(), .destroy(), .updateTheme(input), .updateLocale(locale), .getStatus(), .getSessionId().

Events / callbacks: ready, success, review, error, close, expired, paymentCreated, paymentPending. None of these fire in redirect mode.

Full partner documentation (all modes, config reference, theming, homologation checklist): Integration guide (EN) · Guia de integração (PT-BR).

Config

sessionId is required in production — mint it on your server with @noviuz/kyc-server (or your own client against the API reference) and pass only the opaque id to the browser. Omitting it against any non-local hosted origin throws NoviuzKycError('SESSION_REQUIRED').

Everything else is optional, non-sensitive context: operatorId (optional and non-authoritative once sessionId is present — it's a display hint at most, never authorization), customerType (PF/PJ allowlist), merchantId, orderId, amount, destinationWallet, currency, locale, verification (rail allowlist), theme, primaryColor, appearance, branding, metadata, returnUrl, baseUrl (advanced), closeOnBackdropClick/closeOnEscape, iframeTitle/closeLabel (accessibility text overrides), plus callbacks.

The only exception to "sessionId required" is local/mock development: operatorId + allowClientMintForDevelopment: true + a localhost/127.0.0.1 baseUrl — never valid against a production hosted origin, even with the flag set.

Rejected (throws NoviuzKycError('SENSITIVE_FIELD_REJECTED')): cpf, cnpj, fullName, endUserTaxNumber, bankAccount, pixKey, document, selfie, … and aliases, including inside metadata. See SECURITY.md.

Theming (two tiers)

• Tier 1 — color: { theme: 'dark', primaryColor: '#0a7' }.
• Tier 2 — design tokens: { appearance: { variables: { colorPrimary, radiusMd, fontFamily, … } } }.

Every token value is sanitized before it reaches the hosted DOM.

Redirect mode has no callbacks

redirect() navigates the whole page away — there is no live postMessage channel for callbacks to fire over. On the return page, read the non-authoritative notification instead:

const notification = NoviuzKyc.parseRedirectNotification();
// notification = { sessionId, status?, callbackId? } | null — no signature, no euid, no referenceId.

Compare notification.sessionId against the session your server minted, then reconcile via GET /api/v1/kyc/sessions/{sessionId}/result (@noviuz/kyc-server's getResult(sessionId)) — never act on status from the URL alone. See the Integration guide §3.4 for the full pattern.

Builds

• ESM dist/index.js, CJS dist/index.cjs (zod + @noviuz/kyc-contracts external, deduped by your bundler) — ~8.5KB gzip.
• IIFE dist/noviuz-kyc.js (self-contained, window.NoviuzKyc) — ~25KB gzip. Load the versioned, content-hashed CDN file (/kyc/v2/noviuz-kyc.<hash>.js) with its SRI hash, not a mutable alias.