1. Получите тестовый ключ
- Зарегистрируйтесь на /register и войдите в панель.
- Откройте API-ключи, нажмите Создать ключ и выберите окружение Тестовый.
- Скопируйте ключ. Он начинается с
sk_test_и показывается только один раз — сохраните его в секретах сервера, например в переменной окруженияKYC_SECRET_KEY.
Тестовый режим работает сразу после регистрации. Реальных проверок в нём нет: результат вы выбираете через external_id (см. Тестовый и боевой режимы).
Секретный ключ — только для бэкенда. Никогда не размещайте его в браузере, мобильном приложении или публичном репозитории.
2. Создайте заявителя
Заявитель — это человек, которого вы проверяете. Свяжите его со своим пользователем через external_id (уникален в пределах окружения).
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()
Ответ 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 рядом с пользователем. flow по умолчанию — basic-kyc, он есть в каждом аккаунте.
3. Создайте сессию и откройте ссылку
Сессия — это одна попытка проверки. Она возвращает одноразовый url для hosted-сценария и token для SDK.
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"]
Ответ 201 Created:
{
"id": "ses_01m6yyj5dpxvjjhwm4t3vtqqb7",
"url": "https://kyc.goxost.net/v/Xk7mQ2pL9aR4wTb8",
"token": "eyJ…",
"expires_at": "2026-11-09T10:30:00Z"
}
Откройте url в браузере. На телефоне сценарий попросит согласие, фото документа и селфи; на компьютере сначала предложит QR-код, чтобы продолжить на телефоне. В тестовом режиме принимается любое изображение. Когда появится экран результата, пользователь может вернуться на ваш redirect_url.
Чтобы пользователь остался на вашей странице или в приложении, вместо перенаправления передайте token в kyc.js или Flutter SDK.
4. Примите вебхук
В панели откройте Вебхуки и добавьте https://-эндпоинт (или вызовите POST /webhooks). Подпишитесь как минимум на verification.completed, verification.on_hold и verification.reviewed. Скопируйте секрет подписи (whsec_…) — он показывается только один раз.
Когда решение готово, GOXOST KYC отправляет:
{
"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 (t=<unix time>,v1=<hex>): v1 — это HMAC-SHA256 от "{t}.{raw body}" с вашим секретом, а t должен отличаться от текущего времени не более чем на 5 минут. Быстро ответьте любым 2xx; на другие ответы доставка повторяется.
<?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
В вебхуке нет персональных данных — только ID и решение. События, повторы и журнал доставок описаны в главе Вебхуки.
5. Прочитайте решение
Получите полный результат по verification_id из вебхука.
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()
Ответ 200 OK (сокращённо):
{
"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"
}
В тестовом режиме document.data — синтетический образец (Anna Maria Eriksson из вымышленной страны «Utopia»), а не реальный человек. Если decision равно GREEN, отметьте пользователя как проверенного. Полный список полей — в справочнике API.
Следующие шаги
- Попробуйте другие результаты: создайте заявителей с
external_id, оканчивающимся на-expired,-mismatchили-hold, — см. Тестовый и боевой режимы. - Обработайте повтор после
REDи ручную проверкуON_HOLD— см. Процесс проверки. - Добавьте
Idempotency-Keyв запросы на запись, чтобы повторы после сетевых ошибок были безопасны, — см. Аутентификация. - Перейдите в боевой режим: пройдите верификацию бизнеса в панели и переключитесь на ключ
sk_live_.