Перейти к содержимому
Справочник API Получить API-ключи

С чего начать · Глава 2

Быстрый старт

Проведите первую проверку в тестовом режиме за пять шагов: получите ключ, создайте заявителя, откройте сессию, примите вебхук и прочитайте решение.

5 мин чтения

1. Получите тестовый ключ

  1. Зарегистрируйтесь на /register и войдите в панель.
  2. Откройте API-ключи, нажмите Создать ключ и выберите окружение Тестовый.
  3. Скопируйте ключ. Он начинается с 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_.