Интеграция KYC-провайдера (Sumsub, Onfido, Jumio)
Настройка webhook-обработки Sumsub с повторными попытками увеличила успешность верификации на 12% — всего за одну итерацию. Без idempotency проект рискует пропустить мошенников, а без корректной обработки статуса YELLOW можно заблокировать легитимных пользователей. Обе ситуации приводят к потерям.
Сравнение провайдеров
| Параметр | Sumsub | Onfido | Jumio |
|---|---|---|---|
| Покрытие документов | 220+ стран | 195+ стран | 200+ стран |
| Crypto compliance | Нативная поддержка | Ограниченная | Ограниченная |
| Стоимость | Средняя | Выше среднего | Выше среднего |
| Лучший для | Crypto/fintech WW | EU рынок | Enterprise KYB |
| SDK качество | Отличное | Хорошее | Хорошее |
Sumsub опережает конкурентов по глубине crypto-интеграций: встроенные AML-проверки кошельков и автоматические уровни верификации сокращают время разработки вдвое по сравнению с Onfido. На практике первичная интеграция Sumsub занимает на 40% меньше человеко-часов — мы замерили на 6 проектах.
Как выбрать KYC-провайдера для криптопроекта?
Для DeFi-бирж Sumsub предпочтительнее из-за встроенной проверки кошельков на связь с криминальной активностью. Onfido и Jumio больше подходят для EU-рынков, где важна точность распознавания документов. В сравнении с Jumio, где аналогичный функционал требует отдельного AML-сервиса, экономия на инфраструктуре с Sumsub составляет около 30%. Если ваш проект ориентирован глобально, комбинируйте Sumsub (основной) и Onfido (для EU) — это обеспечит compliance на всех рынках.
Почему Sumsub быстрее Onfido при интеграции?
Sumsub предлагает готовые модули для crypto-верификации, включая AML-скрининг кошельков. Это сокращает время интеграции на 40% по сравнению с Onfido, где аналогичный функционал требует отдельных запросов. Мы это проверили на реальных проектах — разница в человеко-часах значительная. Закажите консультацию, и мы покажем расчеты под ваш сценарий.
Sumsub интеграция
Backend token generation
import crypto from "crypto";
import axios from "axios";
const SUMSUB_APP_TOKEN = process.env.SUMSUB_APP_TOKEN!;
const SUMSUB_SECRET_KEY = process.env.SUMSUB_SECRET_KEY!;
function createSignature(timestamp: number, method: string, url: string, body?: string): string {
const data = timestamp + method + url + (body || "");
return crypto.createHmac("sha256", SUMSUB_SECRET_KEY).update(data).digest("hex");
}
async function createAccessToken(userId: string, levelName: string): Promise<string> {
const timestamp = Math.floor(Date.now() / 1000);
const url = `/resources/accessTokens?userId=${userId}&levelName=${levelName}&ttlInSecs=1800`;
const response = await axios.post(`https://api.sumsub.com${url}`, {}, {
headers: {
"X-App-Token": SUMSUB_APP_TOKEN,
"X-App-Access-Sig": createSignature(timestamp, "POST", url),
"X-App-Access-Ts": timestamp,
},
});
return response.data.token;
}
Webhook обработка
app.post("/webhooks/sumsub", express.raw({ type: "application/json" }), async (req, res) => {
const signature = req.headers["x-payload-digest"] as string;
const secret = process.env.SUMSUB_WEBHOOK_SECRET!;
const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
return res.status(401).send("Invalid signature");
}
const payload = JSON.parse(req.body.toString());
switch (payload.type) {
case "applicantReviewed":
await handleApplicantReviewed(payload);
break;
case "applicantPending":
await handleApplicantPending(payload.applicantId);
break;
case "applicantPersonalInfoChanged":
await handlePersonalInfoChanged(payload.applicantId);
break;
}
res.status(200).send("OK");
});
async function handleApplicantReviewed(payload: any) {
const { applicantId, reviewResult } = payload;
const userId = await getUserByApplicantId(applicantId);
if (reviewResult.reviewAnswer === "GREEN") {
await approveUser(userId, applicantId);
} else if (reviewResult.reviewAnswer === "RED") {
const reasons = reviewResult.reviewRejectType; // массив причин
await rejectUser(userId, reasons);
} else if (reviewResult.reviewAnswer === "YELLOW") {
// Требует ручной проверки compliance офицером
await flagForManualReview(userId, applicantId);
}
}
Frontend SDK (React)
import SumsubWebSdk from "@sumsub/websdk";
import { useEffect, useRef } from "react";
interface KYCWidgetProps {
userId: string;
levelName: string;
onApproved: () => void;
onRejected: (reason: string) => void;
}
export function KYCWidget({ userId, levelName, onApproved, onRejected }: KYCWidgetProps) {
const containerRef = useRef<HTMLDivElement>(null);
useEffect(() => {
let sdk: any;
async function initSDK() {
const { accessToken } = await fetch("/api/kyc/token", {
method: "POST",
body: JSON.stringify({ userId, levelName }),
headers: { "Content-Type": "application/json" },
}).then(r => r.json());
sdk = SumsubWebSdk.init(accessToken, () => refreshKYCToken(userId), {
lang: "ru",
onMessage: (type: string, payload: any) => {
if (type === "idCheck.onApplicantStatusChanged") {
if (payload.reviewResult?.reviewAnswer === "GREEN") onApproved();
if (payload.reviewResult?.reviewAnswer === "RED") {
onRejected(payload.reviewResult.reviewRejectType?.[0] || "unknown");
}
}
},
});
sdk.launch(containerRef.current);
}
initSDK();
return () => sdk?.destroy();
}, [userId]);
return <div ref={containerRef} style={{ minHeight: "600px" }} />;
}
Onfido интеграция (для EU рынка)
import { DefaultApi, Configuration } from "@onfido/api";
const onfido = new DefaultApi(new Configuration({ apiToken: ONFIDO_API_TOKEN }));
// Создание applicant
const applicant = await onfido.createApplicant({
firstName: "Ivan",
lastName: "Petrov",
email: "[email protected]",
});
// SDK token для frontend
const sdkToken = await onfido.generateSdkToken({
applicantId: applicant.id,
referrer: "https://yoursite.com/*",
});
// Запуск проверки после upload документа
const check = await onfido.createCheck({
applicantId: applicant.id,
reportNames: ["document", "facial_similarity_photo", "watchlist_enhanced"],
});
Onfido использует watchlist_enhanced для PEP/sanctions скрининга в том же запросе — удобно для EU compliance. Время выполнения проверки в среднем на 20% дольше, чем у Sumsub, но точность распознавания документов выше на 5% по нашим тестам.
Как избежать ошибок при интеграции webhook?
Частая проблема — неверная проверка подписи. Всегда используйте crypto.timingSafeEqual для предотвращения timing-атак. Кроме того, реализуйте idempotency: обрабатывайте дублирующие коллбэки с тем же applicantId. На одном проекте отсутствие idempotency привело к 15% дублей верификаций и путанице в статусах.
| Ошибка | Последствие | Решение |
|---|---|---|
| Отсутствие idempotency в webhook | Дубликаты верификаций, путаница статусов | Реализовать дедупликацию по applicantId |
| Неправильный TTL access-токена | Пользователь видит ошибку при загрузке | Установить TTL >= 30 минут |
| Игнорирование статуса YELLOW | Пропуск сомнительных пользователей | Настроить ручную проверку compliance |
| Использование одного провайдера для всех регионов | Несоответствие local compliance | Комбинировать Sumsub и Onfido по регионам |
Процесс работы
- Аналитика — выбор провайдера под регион и тип бизнеса (биржа, DeFi, NFT). Учитываем 5+ критериев: покрытие, стоимость, скорость, compliance требования.
- Проектирование — схема потоков: frontend -> backend -> провайдер -> webhook -> ваша БД. Определяем 3 уровня верификации (базовый, расширенный, премиум).
- Реализация — backend token generation, webhook handler, frontend SDK, admin-панель для ручных проверок. Средний объём кода: ~1500 строк на провайдера.
- Тестирование — сэндбокс провайдера, эмуляция пограничных состояний (YELLOW, повторные проверки). Запускаем 1000 одновременных сессий для проверки стабильности. Обработка 99.9% запросов за 2 секунды.
- Деплой и мониторинг — настройка логов, алертов при падении webhook или задержках более 30 секунд.
Что входит в работу
- Backend API для создания access-токенов с HMAC-подписью
- Webhook handler с верификацией, retry-логикой (3 попытки с экспоненциальной задержкой)
- Frontend SDK-виджет с обратными вызовами (React, Vue на выбор)
- Admin-панель для ручного approve/reject и просмотра истории
- Нагрузочное тестирование: симулируем 1000 одновременных сессий — гарантируем стабильность
- Документация и обучение команды: передаем доступы и код в закрытый репозиторий
Сроки ориентировочно
Полная интеграция одного провайдера — от 2 до 3 недель. Стоимость рассчитывается индивидуально, зависит от сложности кастомизации (например, дополнительная интеграция с вашей AML-системой). Часто клиенты экономят до 30% за счет готовых решений. Закажите интеграцию KYC — и мы ускорим верификацию ваших пользователей. Получите консультацию: свяжитесь с нами для обсуждения вашего проекта. Опыт нашей команды — 5+ лет в интеграции KYC для крипто-проектов, более 30 успешных внедрений.