Руководство: как интегрировать KYC API за 1 день (технический пошаговый разбор)

Key takeaways (TL; DR)
 

С Didit вы сможете подключить полноценную проверку личности за несколько часов и запуститься уже сегодня.

Начните быстро с no-code-потока, а по мере роста проекта расширяйтесь с помощью API для большей гибкости.

Базовый план KYC бесплатный и безлимитный — масштабируйтесь с первого дня без дополнительных затрат.

Платформа сохраняет безупречный UX и одновременно соответствует строгим требованиям комплаенса.

Интеграция KYC API часто оказывается сложнее, чем должна быть. Нередки ситуации, когда в документации отсутствуют критичные детали, sandbox ведёт себя иначе, чем продакшен, а webhooks «падают» без объяснений. Если вы это уже проходили — это руководство для вас.

С KYC API Didit вы пройдёте путь от нуля до полной проверки документов и биометрии всего за несколько часов: Face Match 1:1 и Passive Liveness, актуальные статусы в реальном времени через подписанные webhooks и sandbox, который ведёт себя как продакшен. Хотите ещё быстрее? Соберите всё с помощью no-code-потока проверки и выходите в продакшен за минуты.

И самое приятное в KYC API Didit? Он полностью бесплатный. Можно проверять личности бесплатно и без ограничений, начиная масштабирование платформы с нулевой себестоимостью.

Учтите, это материал «от разработчиков для разработчиков»: цель — чтобы ваш поток проверки работал стабильно, сессии проходили за секунды, а статусы были однозначными. Если вы искали «как интегрировать KYC API за один день» — вы по адресу.

Что такое KYC-интеграция и почему она важна для бизнеса?

Интеграция KYC позволяет компаниям выполнять требования идентификации личности с помощью провайдера проверки личности. Такие интеграции автоматизируют валидацию пользователей, что критично для соответствия требованиям по противодействию отмыванию денег (AML).

Обычно KYC внедряют через API (больше гибкости) или с помощью хостингового URL проверки (быстрее запуск). Выбор зависит от потребностей вашего продукта.

Зачем бизнесу KYC?

1. Автоматизация ручных операций. Раньше комплаенс-команды тратили часы на проверку данных онбординга; теперь это безопасно делается за секунды.
2. Соответствие KYC-регулированию. Правила меняются, чтобы бороться с всё более изощрённым фродом. KYC API помогает поддерживать процесс в актуальном и корректном состоянии.
3. Лучшая защита от мошенничества. API убирает ручные шаги и человеческий фактор; антифрод-слой блокирует синтетические личности, дипфейки и поддельные/AI-документы.
4. Оптимизация процессов. Меньше рутины — больше фокуса на онлайновой оценке рисков и выявлении подозрительных паттернов.
5. Неограниченная масштабируемость. Ручные проверки создают узкие места. Автоматический онбординг убирает их, впуская пользователей за секунды без компромиссов по безопасности и точности.
6. Существенная экономия. Интеграция KYC экономит время, ресурсы и деньги. С Didit экономия достигает до 70% по сравнению с «легаси»-поставщиками.

Как интегрировать KYC API Didit (и выйти в продакшен уже сегодня)

Стандартная интеграция Didit опирается на размещённый у Didit workflow, одну сессию проверки на пользователя, URL проверки для запуска потока и подписанные webhooks для синхронизации статусов в реальном времени. Минимальный цикл: создать сессию с вашим workflow_id, отправить пользователя на url проверки, получить webhook с решением и, при необходимости, запросить результат по API. Благодаря модульности Didit вы можете добавлять AML Screening, Proof of Address или Age Estimation без переписывания основы.

Смотрите полную документацию (API Full Flow), если нужно больше деталей.

Перед стартом: API Key, Webhook Secret и настройка Webhook

Зайдите в Business Console (бесплатная регистрация) и откройте API & Webhooks в левой колонке. Там вы получите API Key (для аутентификации в заголовке X-Api-Key) и Webhook Secret Key (для проверки подписи webhooks).

В этом же разделе задайте Webhook URL, на который Didit будет отправлять изменения статуса.

Сохраните значения в переменных окружения (.env) в таком виде:

API_KEY=<YourApiKey>
WEBHOOK_SECRET_KEY=<YourWebhookSecretKey>
WEBHOOK_URL=https://ваше-приложение.com/api/webhooks/didit

Создайте сессию проверки

Следующий шаг — вызвать сервис проверки. Ниже пример — замените workflow_id, callback и API_KEY на реальные данные.

POST /v2/session/
Host: verification.didit.me
Content-Type: application/json
X-Api-Key: {YourApiKey}

{
  "workflow_id": "11111111-2222-3333-4444-555555555555",  // Replace with your chosen workflow
  "callback": "<https://example.com/verification/callback>",
  "vendor_data": "user-123",  // Your user identifier
  "metadata": {
    "user_type": "premium",
    "account_id": "ABC123"
  },
  "contact_details": {
    "email": "ivan.ivanov@example.com",
    "email_lang": "ru",
    "phone": "+74951234567"
  }
}

В ответе вы получите, среди прочего, session_id, начальный status и url — ссылку, по которой пользователь проходит размещённый у Didit поток:

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 1234,
  "session_token": "abcdef123456",
  "vendor_data": "user-123",
  "metadata": { "user_type": "premium", "account_id": "ABC123" },
  "status": "Not Started",
  "workflow_id": "example_workflow_id",
  "callback": "<https://example.com/verification/callback>",
  "url": "<https://verify.didit.me/session/abcdef123456>"
}

Больше подробностей и примеров кода — в разделе Create Session документации.

Запустите UI проверки (редирект или встраивание)

Имея url проверки, можно сделать редирект (самый простой вариант) или встроить поток в <iframe>, чтобы сохранить ваш макет. Didit организует захват документа, селфи и проверку «живости» по вашему workflow.

После каждого шага сессия меняет статус, и об этом приходит webhook.

Результаты сессии проверки

Результаты доступны двумя способами: Webhooks (рекомендуется) или запрос по API по требованию. С webhooks ваш бэкенд получает уведомления о каждом изменении статуса в реальном времени — без polling и с единым источником правды.

Чтобы гарантировать подлинность webhook, всегда проверяйте подпись в заголовке X-Signature, используя ваш WEBHOOK_SECRET_KEY. Также проверяйте заголовок X-Timestamp и отклоняйте запросы вне короткого окна (например, 5 минут), чтобы предотвращать фрод и повторные воспроизведения.

В разделе Webhooks документации есть все детали и дополнительные примеры.

Если нужно сверить статусы (например, webhook не дошёл), можно получить решение по запросу:

GET <https://verification.didit.me/v2/session/{sessionId}/decision/>
X-Api-Key: <YourApiKey>

Последовательно сопоставляйте статусы в вашей системе (например: Not Started → In Progress → In Review → Approved / Declined / Abandoned) и отражайте каждый переход в UI и метриках. Это исключит неоднозначность между продуктом, поддержкой и аналитикой.

Больше контроля и гибкости: самостоятельные API-модули проверки

Нужен более тонкий контроль? Воспользуйтесь самостоятельными API Didit. Помимо «всё-в-одном» KYC API (ID Verification, Face Match 1:1 и Passive Liveness), вы можете собирать свои процессы и точечные проверки, подключая только нужные функции.

Что дают самостоятельные API Didit?

• ID Verification — проверка удостоверения личности и извлечение ключевых данных.
• Face Match 1:1 — сравнение портрета в документе с «живым» селфи.
• Age Estimation — оценка возраста для бесшовного онбординга в продуктах с возрастными ограничениями.
• Proof of Address — подтверждение адреса по официальным документам и счетам за услуги.
• AML Screening — проверка по спискам наблюдения, санкциям, PEP и негативным СМИ.
• Face Search 1:N — поиск лица в базе для предотвращения дублей.
• Passive Liveness — подтверждение реального присутствия пользователя.
• Database Validation — проверка личности по нац./междунар. базам (1x1 и 2x2).
• Phone Verification — проверка телефонов через OTP.
• Email Verification — проверка e-mail через OTP.

Сколько стоит использование KYC API?

Didit предлагает единственный бесплатный и безлимитный план для проверки личности. Это означает, что стоимость использования KYC API равна нулю, будь то единичные вызовы или сотни.

Без «мелкого шрифта», контрактов и жёстких пакетов. Didit — простой, открытый, гибкий и экономичный вариант с экономией до 70% относительно устоявшихся решений. Модель монетизации основана на дополнительных возможностях (AML Screening, Proof of Address, Phone/Email Verification и т. п.) и использовании самостоятельных API.

Ознакомьтесь с ценами на самостоятельные API.