1. Sinov kalitini oling
- /register sahifasida hisob oching va panelga kiring.
- API kalitlari boʻlimini oching, Kalit yaratish ni bosing va Sinov muhitini tanlang.
- Kalitni nusxalang. U
sk_test_bilan boshlanadi va faqat bir marta koʻrsatiladi — uni serveringiz maxfiy sozlamalarida saqlang, masalanKYC_SECRET_KEYmuhit oʻzgaruvchisida.
Sinov rejimi roʻyxatdan oʻtgan zahoti ishlaydi. U haqiqiy tekshiruv oʻtkazmaydi: natijani external_id orqali oʻzingiz tanlaysiz (Sinov va ishchi rejim bobiga qarang).
Maxfiy kalit faqat backend uchun. Uni hech qachon brauzerga, mobil ilovaga yoki ochiq repozitoriyga qoʻymang.
2. Arizachi yarating
Arizachi — siz tekshirayotgan odam. Uni external_id orqali oʻz foydalanuvchingizga bogʻlang (har bir muhitda yagona boʻladi).
curl https://kyc.goxost.net/api/v1/applicants \
-H "Authorization: Bearer $KYC_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"external_id": "user-8812", "locale": "en"}'
<?php
// composer require guzzlehttp/guzzle
$kyc = new GuzzleHttp\Client([
'base_uri' => 'https://kyc.goxost.net/api/v1/',
'headers' => ['Authorization' => 'Bearer ' . getenv('KYC_SECRET_KEY')],
]);
$applicant = json_decode($kyc->post('applicants', [
'json' => ['external_id' => 'user-8812', 'locale' => 'en'],
])->getBody(), true);
const KYC = 'https://kyc.goxost.net/api/v1';
const headers = {
Authorization: `Bearer ${process.env.KYC_SECRET_KEY}`,
'Content-Type': 'application/json',
};
const applicant = await fetch(`${KYC}/applicants`, {
method: 'POST',
headers,
body: JSON.stringify({ external_id: 'user-8812', locale: 'en' }),
}).then((r) => r.json());
import os
import requests
KYC = "https://kyc.goxost.net/api/v1"
headers = {"Authorization": f"Bearer {os.environ['KYC_SECRET_KEY']}"}
applicant = requests.post(
f"{KYC}/applicants",
headers=headers,
json={"external_id": "user-8812", "locale": "en"},
).json()
Javob 201 Created:
{
"id": "apl_01m6yyj5d7qnxppat520rwg0mb",
"external_id": "user-8812",
"flow": "basic-kyc",
"locale": "en",
"status": "init",
"decision": null,
"risk_score": null,
"last_verification_id": null,
"metadata": {},
"purpose": null,
"valid_until": null,
"created_at": "2026-11-09T10:00:00Z",
"updated_at": "2026-11-09T10:00:00Z"
}
id ni foydalanuvchingiz yonida saqlang. flow sukut boʻyicha basic-kyc — bu senariy har bir hisobda bor.
3. Sessiya yarating va havolani oching
Sessiya — bitta tekshiruv urinishi. U hosted senariy uchun bir martalik url va SDK lar uchun token qaytaradi.
curl https://kyc.goxost.net/api/v1/applicants/apl_01m6yyj5d7qnxppat520rwg0mb/sessions \
-H "Authorization: Bearer $KYC_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"redirect_url": "https://shop.example/kyc/done", "expires_in": 1800}'
$session = json_decode($kyc->post("applicants/{$applicant['id']}/sessions", [
'json' => ['redirect_url' => 'https://shop.example/kyc/done', 'expires_in' => 1800],
])->getBody(), true);
header('Location: ' . $session['url']);
const session = await fetch(`${KYC}/applicants/${applicant.id}/sessions`, {
method: 'POST',
headers,
body: JSON.stringify({ redirect_url: 'https://shop.example/kyc/done', expires_in: 1800 }),
}).then((r) => r.json());
res.redirect(session.url);
session = requests.post(
f"{KYC}/applicants/{applicant['id']}/sessions",
headers=headers,
json={"redirect_url": "https://shop.example/kyc/done", "expires_in": 1800},
).json()
# redirect the user to session["url"]
Javob 201 Created:
{
"id": "ses_01m6yyj5dpxvjjhwm4t3vtqqb7",
"url": "https://kyc.goxost.net/v/Xk7mQ2pL9aR4wTb8",
"token": "eyJ…",
"expires_at": "2026-11-09T10:30:00Z"
}
url ni brauzerda oching. Telefonda senariy rozilik, hujjat surati va selfi soʻraydi; kompyuterda esa avval telefonda davom etish uchun QR kod taklif qiladi. Sinov rejimida istalgan rasm qabul qilinadi. Natija ekrani chiqqach, foydalanuvchi sizning redirect_url ingizga qaytishi mumkin.
Foydalanuvchini sahifangizda yoki ilovangizda qoldirish uchun yoʻnaltirish oʻrniga token ni kyc.js yoki Flutter SDK ga bering.
4. Webhook qabul qiling
Panelda Webhooklar boʻlimini oching va https:// endpoint qoʻshing (yoki POST /webhooks ni chaqiring). Kamida verification.completed, verification.on_hold va verification.reviewed hodisalariga obuna boʻling. Imzo sirini (whsec_…) nusxalang — u faqat bir marta koʻrsatiladi.
Qaror tayyor boʻlganda GOXOST KYC quyidagini yuboradi:
{
"id": "evt_01m6yyj5f3k8w2c9r4tq7vbn5d",
"type": "verification.completed",
"created_at": "2026-11-09T10:04:12Z",
"env": "sandbox",
"data": {
"applicant_id": "apl_01m6yyj5d7qnxppat520rwg0mb",
"external_id": "user-8812",
"verification_id": "ver_01m6yyj5dztvhsx7kk9h8qwcnf",
"decision": "GREEN",
"decision_type": null,
"reject_labels": []
}
}
KYC-Signature sarlavhasini (t=<unix time>,v1=<hex>) tekshiring: v1 — sizning siringiz bilan "{t}.{raw body}" dan olingan HMAC-SHA256, t esa 5 daqiqa ichida boʻlishi kerak. Tezda istalgan 2xx bilan javob bering; boshqa javoblarda yuborish takrorlanadi.
<?php
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_KYC_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $sig); // ['t' => …, 'v1' => …]
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, getenv('KYC_WEBHOOK_SECRET'));
$fresh = abs(time() - (int) ($sig['t'] ?? 0)) <= 300;
if (! isset($sig['v1']) || ! $fresh || ! hash_equals($expected, $sig['v1'])) {
http_response_code(400);
exit;
}
$event = json_decode($body, true);
// queue your own processing here, then answer fast
http_response_code(200);
import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.post('/kyc/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const sig = Object.fromEntries(
(req.get('KYC-Signature') ?? '').split(',').map((part) => part.split('=', 2)),
);
const expected = crypto
.createHmac('sha256', process.env.KYC_WEBHOOK_SECRET)
.update(`${sig.t}.`)
.update(req.body) // raw bytes, not re-serialised JSON
.digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) <= 300;
const valid = typeof sig.v1 === 'string' && sig.v1.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(sig.v1), Buffer.from(expected));
if (!fresh || !valid) return res.sendStatus(400);
const event = JSON.parse(req.body);
// queue your own processing here, then answer fast
res.sendStatus(200);
});
import hashlib, hmac, os, time
from flask import Flask, abort, request
app = Flask(__name__)
@app.post("/kyc/webhook")
def kyc_webhook():
header = request.headers.get("KYC-Signature", "")
sig = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
t = sig.get("t", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
abort(400)
body = request.get_data() # raw bytes
expected = hmac.new(
os.environ["KYC_WEBHOOK_SECRET"].encode(), f"{t}.".encode() + body, hashlib.sha256
).hexdigest()
if not hmac.compare_digest(expected, sig.get("v1", "")):
abort(400)
event = request.get_json()
# queue your own processing here, then answer fast
return "", 200
Webhookda shaxsiy maʼlumot yoʻq — faqat ID lar va qaror. Hodisalar, qayta yuborishlar va yetkazish jurnali Webhooklar bobida.
5. Qarorni oʻqing
Webhookdagi verification_id bilan toʻliq natijani oling.
curl https://kyc.goxost.net/api/v1/verifications/ver_01m6yyj5dztvhsx7kk9h8qwcnf \
-H "Authorization: Bearer $KYC_SECRET_KEY"
$verification = json_decode(
$kyc->get("verifications/{$event['data']['verification_id']}")->getBody(), true
);
const verification = await fetch(
`${KYC}/verifications/${event.data.verification_id}`,
{ headers },
).then((r) => r.json());
verification = requests.get(
f"{KYC}/verifications/{event['data']['verification_id']}", headers=headers
).json()
Javob 200 OK (qisqartirilgan):
{
"id": "ver_01m6yyj5dztvhsx7kk9h8qwcnf",
"applicant_id": "apl_01m6yyj5d7qnxppat520rwg0mb",
"session_id": "ses_01m6yyj5dpxvjjhwm4t3vtqqb7",
"decision": "GREEN",
"decision_type": null,
"reject_labels": [],
"risk_score": 0.05,
"stale": false,
"checks": [
{ "name": "document", "status": "pass", "score": 0.99, "labels": [] },
{ "name": "face_match", "status": "pass", "score": 0.99, "labels": [] },
{ "name": "liveness", "status": "pass", "score": 0.99, "labels": [] }
],
"document": {
"type": "passport",
"country": "UTO",
"data": {
"first_name": "ANNA MARIA",
"last_name": "ERIKSSON",
"full_name": "ERIKSSON ANNA MARIA",
"birth_date": "1992-08-12",
"number": "L898902C3",
"expiry_date": "2032-04-15"
}
},
"valid_until": "2028-11-09T10:04:12Z",
"review_deadline_at": null,
"reviewed_by": null,
"reviewed_at": null,
"created_at": "2026-11-09T10:03:40Z",
"completed_at": "2026-11-09T10:04:12Z"
}
Sinov rejimida document.data — sintetik namuna (xayoliy «Utopia» davlatining Anna Maria Eriksson nomidagi hujjati), haqiqiy odam emas. Agar decision GREEN boʻlsa, foydalanuvchingizni tasdiqlangan deb belgilang. Maydonlarning toʻliq roʻyxati — API maʼlumotnomasida.
Keyingi qadamlar
- Boshqa natijalarni sinab koʻring:
external_idsi-expired,-mismatchyoki-holdbilan tugaydigan arizachilar yarating — Sinov va ishchi rejim bobiga qarang. REDdan keyingi qayta urinishni vaON_HOLDdagi qoʻlda koʻrib chiqishni qayta ishlang — Tekshiruv jarayoni.- Yozuvchi soʻrovlarga
Idempotency-Keyqoʻshing, shunda tarmoq xatosidan keyingi takror xavfsiz boʻladi — Autentifikatsiya. - Ishchi rejimga oʻting: panelda biznes tasdiqlovini yakunlang va
sk_live_kalitga almashing.