Интеграция KYC-провайдера для криптопроектов: Sumsub, Onfido, Jumio

Интеграция KYC-провайдера (Sumsub, Onfido, Jumio)

Настройка webhook-обработки Sumsub с повторными попытками увеличила успешность верификации на 12% — всего за одну итерацию. Без idempotency проект рискует пропустить мошенников, а без корректной обработки статуса YELLOW можно заблокировать легитимных пользователей. Обе ситуации приводят к потерям.

Сравнение провайдеров

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% дублей верификаций и путанице в статусах.

Процесс работы

1. Аналитика — выбор провайдера под регион и тип бизнеса (биржа, DeFi, NFT). Учитываем 5+ критериев: покрытие, стоимость, скорость, compliance требования.
2. Проектирование — схема потоков: frontend -> backend -> провайдер -> webhook -> ваша БД. Определяем 3 уровня верификации (базовый, расширенный, премиум).
3. Реализация — backend token generation, webhook handler, frontend SDK, admin-панель для ручных проверок. Средний объём кода: ~1500 строк на провайдера.
4. Тестирование — сэндбокс провайдера, эмуляция пограничных состояний (YELLOW, повторные проверки). Запускаем 1000 одновременных сессий для проверки стабильности. Обработка 99.9% запросов за 2 секунды.
5. Деплой и мониторинг — настройка логов, алертов при падении 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 успешных внедрений.