Web SDK

Reference for kita-risk.js: installation, KitaRisk.create, callbacks, events and methods.

Installation

Load the script from your Kita host. It is small, has no dependencies and defines one global, KitaRisk. Always load it from Kita rather than bundling a copy, so fixes reach you without a release.

<script src="https://<your-kita-host>/sdk/v1/kita-risk.js"></script>

If you set a Content Security Policy, allow your Kita host in script-src, style-src and frame-src.

KitaRisk.create(options)

Returns a handle. Nothing is shown until you call open().

Option	Type	Required	Description
`sessionId`	string	yes	`session_id` from create session.
`clientToken`	string	yes	`client_token` from the same response. Expires after 30 minutes.
`container`	element or selector	no	Render inline inside this element. Omit for a modal dialog.
`language`	`'en'` or `'es'`	no	Language of the flow. Default `'en'`.
`connectUrl`	string	no	`connect_url` from the session response. Needed only when the script is served from a different host than the flow.
`onSubmitted`	function	no	`({ sessionId, status: 'accepted' })`. The borrower shared their files and tapped Done.
`onExit`	function	no	`({ sessionId })`. The borrower closed the flow before finishing. Uploaded files are kept until the session expires, so they can resume.
`onError`	function	no	`({ code, sessionId })`. See errors. Most are shown to the borrower and recoverable.
`onEvent`	function	no	`({ name, sessionId })`. Progress events for your analytics.

Callbacks are UI signals, not proof

Anything that runs in the browser can be faked. Treat onSubmitted as a reason to update your page, and rely on your server's view of the session for decisions.

Events

`name`	When
`consent_recorded`	The borrower accepted the data notice.
`documents_added`	One or more files uploaded and passed validation.
`documents_submitted`	The borrower shared the files. Processing starts.

Methods

Method	Description
`open()`	Show the flow. Safe to call again after `exit()`.
`back()`	Move back one screen, for hosts with their own Back button (Android).
`exit()`	Close the flow and fire `onExit`.
`destroy()`	Close, remove listeners and discard the token. Create a new handle to reopen.

// Modal: a centered dialog on desktop, full screen on phones.
KitaRisk.create({ sessionId, clientToken, onSubmitted }).open();
 
// Inline: fills the element you give it. Size the element yourself,
// at least 360 × 640 CSS pixels.
KitaRisk.create({ sessionId, clientToken, container: '#kita', onSubmitted }).open();

If the borrower leaves and comes back, ask your server for a new token with POST /v1/risk/sessions/{id}/client-token and call create() again with the same sessionId. Files already uploaded are still there. A session that was already submitted opens on its receipt.

React

import { useEffect, useRef } from 'react';
 
export function StatementUpload({ sessionId, clientToken, onDone }: Props) {
  const slot = useRef<HTMLDivElement>(null);
  useEffect(() => {
    const kita = window.KitaRisk.create({ sessionId, clientToken, container: slot.current!, onSubmitted: onDone });
    kita.open();
    return () => kita.destroy();
  }, [sessionId, clientToken, onDone]);
  return <div ref={slot} style={{ height: 720 }} />;
}

Browser support

Current Chrome, Safari, Firefox and Edge, on desktop and mobile. The flow is keyboard accessible, announces progress to screen readers and honors reduced motion. It needs HTTPS everywhere except localhost.