Skip to content
API reference Get API keys

SDKs and plugins · Chapter 10

Web SDK

Embed the verification flow into your own web page with kyc.js. The applicant never leaves your site, and you get events as the flow moves forward.

4 min read

How it works

  1. Your server creates an applicant and a session (POST /applicants/{id}/sessions) and passes the session token to the page.
  2. The page loads kyc.js and calls KYC.init() with the token. The flow opens in an iframe inside your container.
  3. The applicant takes the document photo and the selfie. On a desktop without a camera the flow offers a QR code to continue on a phone.
  4. onComplete fires in the browser, and your server receives the webhook with the decision.
Important

The secret key stays on your server. The page only gets the session token, which works for one session and expires with it.

Quick start

Create the session on your server (see Quickstart) and render its token into the page:

<div id="kyc"></div>

<script src="https://kyc.goxost.net/sdk/kyc.js"></script>
<script>
  const flow = KYC.init({
    token: 'eyJ…',            // session token from your server
    container: '#kyc',
    locale: 'en',             // uz | ru | en
    onReady() {
      console.log('Flow loaded');
    },
    onComplete(result) {
      // UX only: show a "thank you" screen, then ask your server for the status
      showThankYou(result.decision);
    },
    onError(error) {
      if (error.code === 'session_expired' || error.code === 'link_invalid') {
        restartWithNewSession(); // ask your server for a new session
      }
    },
  });
</script>

Call flow.destroy() to remove the iframe and stop listening, for example when the user closes your modal or navigates away in a single-page app.

Options

KYC.init(options) returns { destroy() }.

Option Type Description
token string, required Session token from POST /applicants/{id}/sessions
container CSS selector or HTMLElement, required Element the iframe is placed into; its current content is replaced
locale uz, ru, en Language of the flow. Without it: the applicant's locale, then the browser language
onReady() function The flow has loaded
onComplete(result) function The applicant finished. result is { decision, decision_type, reject_labels }
onError(error) function The flow cannot continue. error is { code }
onEvent(event) function Every event below, including ready, complete and error

KYC.init throws KYC: invalid token for an empty or malformed token and KYC: container not found when the selector matches nothing.

The iframe takes the full width of the container. Its height starts at 640 px and then follows the content (at least 320 px), so do not set a fixed height on the container.

Events

type Fields When
ready — The flow has loaded
step step: handoff, consent, document, liveness, processing The applicant moved to a new step (handoff is the "continue on phone" screen)
complete decision (GREEN, RED, ON_HOLD), decision_type (final, retry or null), reject_labels The result is ready
error code The flow stopped
resize height The content height changed (the SDK resizes the iframe for you)

Error codes you should handle:

code Meaning What to do
link_invalid The session is unknown, used or closed Create a new session
session_expired The session expired during the flow Create a new session
session_reset The applicant was reset while the flow was open Create a new session
network Connection problem Ask the user to check the connection and retry
unknown Any other error Retry; if it repeats, create a new session

Other API error codes from the flow may also arrive — treat unknown codes like unknown.

Security

  • onComplete is for the interface only. Messages from the iframe can be faked in the browser. Take the final decision on your server — from the webhook or from GET /verifications/{id} — before you unlock anything.
  • Events carry only codes and the decision — never names, document data or images.
  • If you embed the iframe yourself instead of using kyc.js, accept a message only when event.origin is https://kyc.goxost.net, event.source is your iframe's contentWindow and event.data.source is kyc-flow. kyc.js does these checks for you.

Content Security Policy and camera

If your site sends a Content Security Policy, allow GOXOST KYC:

Content-Security-Policy: script-src 'self' https://kyc.goxost.net; frame-src https://kyc.goxost.net

If your site sends a Permissions-Policy header, it must let the iframe use the camera:

Permissions-Policy: camera=(self "https://kyc.goxost.net")

The page must be served over HTTPS — browsers block the camera on plain HTTP. The flow page itself allows embedding on any site; the session token is what protects it.

You can skip kyc.js and send the applicant to the session url (https://kyc.goxost.net/v/Xk7mQ2pL9aR4wTb8) — by redirect, in a new tab, by SMS or by email.

  • Set redirect_url (HTTPS only) when you create the session: at the end the flow shows a Return to the service button that opens it. In embedded mode this button is not shown.
  • expires_in sets the link lifetime: 60–1800 seconds, default 1800.
  • An applicant has one active session. Creating a new one closes the previous one; a closed link returns 410 and the page tells the user the link is no longer valid.
  • The redirect is not proof of the result either — read the decision on your server.

Every page of the flow carries a small "Powered by GOXOST KYC" mark.