How it works
- Your server creates an applicant and a session (
POST /applicants/{id}/sessions) and passes the sessiontokento the page. - The page loads
kyc.jsand callsKYC.init()with the token. The flow opens in an iframe inside your container. - 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.
onCompletefires in the browser, and your server receives the webhook with the decision.
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
onCompleteis 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 fromGET /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 whenevent.originishttps://kyc.goxost.net,event.sourceis your iframe'scontentWindowandevent.data.sourceiskyc-flow.kyc.jsdoes 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.
Hosted link instead of embedding
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_insets 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
410and 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.