Asosiy qismga oʻtish
API hujjati API kalitini olish

Boshlash · 2-bob

Tez boshlash

Sinov rejimida birinchi tekshiruvni besh qadamda oʻtkazing: kalit oling, arizachi yarating, sessiya oching, webhook qabul qiling va qarorni oʻqing.

5 daqiqa oʻqish

1. Sinov kalitini oling

  1. /register sahifasida hisob oching va panelga kiring.
  2. API kalitlari boʻlimini oching, Kalit yaratish ni bosing va Sinov muhitini tanlang.
  3. Kalitni nusxalang. U sk_test_ bilan boshlanadi va faqat bir marta koʻrsatiladi — uni serveringiz maxfiy sozlamalarida saqlang, masalan KYC_SECRET_KEY muhit 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).

Muhim

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_id si -expired, -mismatch yoki -hold bilan tugaydigan arizachilar yarating — Sinov va ishchi rejim bobiga qarang.
  • RED dan keyingi qayta urinishni va ON_HOLD dagi qoʻlda koʻrib chiqishni qayta ishlang — Tekshiruv jarayoni.
  • Yozuvchi soʻrovlarga Idempotency-Key qoʻshing, shunda tarmoq xatosidan keyingi takror xavfsiz boʻladi — Autentifikatsiya.
  • Ishchi rejimga oʻting: panelda biznes tasdiqlovini yakunlang va sk_live_ kalitga almashing.