Перейти к основному содержанию
Используйте специальный эндпоинт кошельков, чтобы верифицировать человека из вашего приложения. Создавать или публиковать сценарий и передавать workflow_id не нужно. Ваш бэкенд запускает верификацию и получает её результат, а ваш интерфейс проводит человека через обязательную аутентификацию в кошельке.
Интеграция через API по-прежнему требует, чтобы человек прошёл аутентификацию и подтвердил передачу своих данных личности. Без этого взаимодействия верифицировать человека, отправив только его личный идентификатор, нельзя.

Как работает верификация

  1. Ваш бэкенд проверяет каталог кошельков, затем вызывает эндпоинт запуска доступного кошелька, используя API-ключ вашего приложения.
  2. Didit возвращает справочный номер верификации и действие, которое должен выполнить человек.
  3. Ваше приложение открывает страницу аутентификации или показывает инструкции кошелька по подтверждению.
  4. Человек проходит аутентификацию в своём кошельке.
  5. Ваш бэкенд получает подтверждённый результат и обрабатывает уведомления о завершении.
Аутентификация в кошельке выполняется асинхронно. Успешный запрос на запуск означает, что аутентификация начата, но не означает, что личность подтверждена. Всегда проверяйте итоговый результат, прежде чем считать человека верифицированным.

Интеграция на стороне бэкенда

Используйте Список цифровых ID-кошельков, чтобы получить актуальные эндпоинты, обязательные поля и доступность кошельков для вашего приложения. Храните x-api-key на своём бэкенде. Не размещайте его в браузерном бандле или мобильном приложении. Для каждой новой попытки верификации используйте отдельный Idempotency-Key, а при повторе того же запроса на запуск передавайте этот же ключ. Изменение запроса при повторном использовании ключа считается конфликтом, а не новой попыткой верификации. У каждого кошелька есть собственный URL запуска, например /v3/id-verification/wallets/ftn/ для Finnish Trust Network. request_id идентифицирует автономную верификацию для последующих операций. Используйте vendor_data для собственной ссылки или идентификации, до 2 000 байт в UTF-8, а metadata для необязательного JSON-объекта. Оба поля возвращаются вместе с результатом и webhook о завершении. Эти операции используют API-ключ приложения, которое запустило верификацию. Опрос и доступность аутентификации зависят от выбранного кошелька. Отмена отклоняет ожидающую верификацию без оплаты и возвращает завершённую верификацию без изменений. Для Smart-ID и Mobile-ID отмена, поступившая во время проверки подтверждения, ожидает завершения этого опроса несколько секунд. Затем верификация отклоняется или возвращается со статусом verified, если человек уже подтвердил её. Верификацию, которую человек завершает в этот момент, отменить нельзя: ответ будет 409 с error: "verification_in_progress" и заголовком Retry-After. Повторите запрос через указанное в заголовке количество секунд, чтобы получить завершённый результат.

Регистрация адреса возврата

Кошельки с перенаправлением возвращают человека в ваше приложение после аутентификации. Зарегистрируйте точное имя хоста до запуска верификации:
Затем передайте в запросе на запуск HTTPS-return_url, например https://app.example.com/identity/complete. В allowed_return_hosts указывайте только имена хостов, без схемы, пути и подстановочных знаков. Регистрируйте каждый используемый поддомен отдельно, до 20 хостов. Обновление allowed_return_hosts заменяет зарегистрированный список, поэтому включите все имена хостов, которые хотите сохранить. GET /v3/webhook/ возвращает текущий список; см. Конфигурация webhook. Для регистрации адреса возврата не нужны ни сценарий, ни домен White label. Адресом возврата служит страница возврата в браузере, а webhook о завершении настраивайте отдельно для вашего бэкенда.

Пример: Finnish Trust Network

После регистрации имени хоста для возврата запустите верификацию Finnish Trust Network:
Сохраните возвращённый request_id и перенаправьте браузер человека на wallet_verification.next_action.url, когда его type равен redirect. После возврата человека получите результат с вашего бэкенда:
Проверьте wallet_verification.outcome: Используйте данные личности только тогда, когда исход равен verified, а simulated равен false для реальной проверки личности. Ответ в статусе ожидания может содержать следующее действие; в итоговых ответах нет следующего действия.

Варианты аутентификации

Кошельки с перенаправлением возвращают URL аутентификации. Откройте этот URL в браузере пользователя, дайте ему пройти процесс аутентификации в кошельке и вернуть его на зарегистрированный адрес назначения. Результат читайте на своём бэкенде, а не доверяйте параметру возвратного URL как доказательству личности. Smart-ID и Mobile-ID используют запрос на подтверждение на телефоне пользователя. Ваш интерфейс собирает нужный персональный идентификатор; Mobile-ID также требует связанный номер телефона. Покажите код сравнения и попросите пользователя подтвердить вход только в том случае, если он совпадает с кодом на его телефоне. PIN-код вводится в окне кошелька или телефона, но никогда не вводится в вашей форме и не передаётся в API-запросе. Опрашивайте статус со своего бэкенда с интервалом, указанным в возвращённом poll_interval_seconds, чтобы получать обновления о запросе. Didit также в фоновом режиме проверяет ожидающие подтверждения на телефоне, поэтому уведомление о завершении может поступить на ваш webhook уже после того, как пользователь закроет вашу страницу. Google Wallet запрашивается с вашей страницы или из вашего приложения через Digital Credentials API, без перенаправления; см. Кошельки Digital Credentials (Google Wallet). Доступный способ взаимодействия зависит от выбранного кошелька. Не предполагайте, что каждый кошелёк поддерживает встроенную форму, QR-код или аутентификацию без браузера.

Кошельки Digital Credentials (Google Wallet)

Google Wallet запрашивается непосредственно с вашей веб-страницы или из Android-приложения с помощью W3C Digital Credentials API. Перенаправления нет, страницы, размещённой Didit, нет, и QR-кода Didit нет. Кошелёк доступен в продакшн-среде и в песочнице. Приложениям в песочнице регистрация не нужна. Каждое продакшн-приложение регистрируется один раз в консоли (шаг «Верификация личности», строка Google Wallet, Зарегистрироваться в Google), прежде чем сможет использовать Google Wallet. Актуальный список того, что ваше приложение может запустить прямо сейчас, см. в Список цифровых ID-кошельков.
1

Начните с вашего origin

Ваш бэкенд вызывает POST /v3/id-verification/wallets/google-wallet/ с country пользователя (USA, GBR, BRA, SGP или TWN) и origin, с которого будет запрашиваться кошелёк. Параметр origin представляет собой HTTPS-origin вашей страницы, например https://app.example.com, хост которого должен быть одним из ваших зарегистрированных имён хостов для возврата или доменом вашего White label. Для Android-приложения это android:apk-key-hash:, после которого идёт base64-представление SHA-256 сертификата подписи вашего приложения, без символов заполнения. Кошелёк отклоняет запрос, сделанный с любого другого origin. Параметра return_url нет.
2

Запросите кошелёк в рамках действия пользователя

Ответ содержит wallet_verification.interaction = "digital_credentials" и next_action.type = "request_digital_credential". Передайте next_action.digital_credentials.request браузеру или Android Credential Manager по нажатию или клику на том origin, с которого вы начали. В десктопном браузере, если кошелёк находится на другом устройстве, браузер показывает собственный QR-код.
3

Отправьте то, что вернул кошелёк

Передайте полученные {protocol, data} на свой бэкенд, а оттуда отправьте их в POST /v3/id-verification/wallets/verifications/{request_id}/response/ в виде {"response": {...}}. Запрос можно отправить только один раз; повторная отправка возвращает уже принятое решение по верификации.
4

Получите результат

Ответ на отправку содержит принятое решение по верификации. Прочитать его можно также через GET /v3/id-verification/wallets/verifications/{request_id}/ или получить в webhook о завершении.
В браузере запрашивайте кошелёк из обработчика клика:
Предлагайте этот способ только там, где браузер его поддерживает, например когда "DigitalCredential" in window возвращает true. navigator.credentials.get должен вызываться в рамках действия пользователя, поэтому вызывайте его из обработчика клика, а не после асинхронного шага. На Android используйте Jetpack Credential Manager (androidx.credentials версии 1.5.0 или новее) с тем же запросом:
Ошибки, которые нужно обработать: Верификация учётных данных, не прошедших проверку, является принятым решением с результатом failed, а не ответом с ошибкой. Из кошелька передаются только те поля, которые запросила верификация, а результат содержит атрибуты личности, которые вернул кошелёк. ID-пропуск Google Wallet и мобильное водительское удостоверение штата США не возвращают портретное фото. В приложении в песочнице процесс имитируется с теми же шагами, и в ответе возвращается simulated: true. Любой отправленный ответ принимает решение по верификации в соответствии с sandbox_scenario, поэтому вы можете реализовать полный сценарий в браузере или приложении без настоящего учётного документа.

Webhook-уведомления о завершении

Настройте адрес назначения webhook на уровне приложения для события status.updated по руководству по интеграции webhook. Для описанной здесь структуры решения используйте webhook_version: "v3". Проверяйте подпись webhook на своём бэкенде, прежде чем его обрабатывать. session_id в webhook совпадает с request_id, который возвращает API кошельков. Завершённая идентификация через кошелёк появляется в массиве decision.id_verifications webhook с verification_method: "wallet". Тот же идентификатор можно использовать, чтобы получить результат через специализированный API кошельков. Обрабатывайте уведомления об одобрении и отклонении, включая уведомления об отменённых и истёкших верификациях. Делайте обработчик webhook идемпотентным, потому что для неудачных доставок выполняются повторные попытки. Возврат из браузера не является webhook о завершении, а параметры его строки запроса не служат доказательством личности.

Возвращаемые данные идентификации

Используйте нормализованные поля идентификационных данных для имён и дат рождения, если эти поля возвращаются. Атрибуты, специфичные для кошелька, описывают сведения о личности, которые передаёт выбранный кошелёк. Доступные атрибуты зависят от кошелька и страны. Успешная аутентификация личности не означает, что портрет, адрес или любой другой запрошенный атрибут доступен.

Тестирование в песочнице

Приложение в режиме песочницы Didit имитирует верификацию через кошелёк без обращения к провайдеру кошелька и без списания кредитов. В ответе такие запросы помечаются wallet_verification.simulated: true. Имитированное одобрение содержит тестовые данные, а не подтверждённую реальную личность. Для кошелька с перенаправлением перейдите по возвращённому URL, чтобы проверить обратный вызов и возврат в ваше приложение. Для Smart-ID или Mobile-ID используйте endpoint опроса, чтобы завершить имитированное одобрение; уведомление на телефон не отправляется. Чтобы проверить обработку ошибок, при создании запроса задайте sandbox_scenario со значением wallet_cancelled, wallet_timeout или wallet_provider_error. Боевые приложения отклоняют sandbox_scenario. Имитация в песочнице Didit отделена от тестирования в собственной тестовой среде провайдера. Успешная имитация не подтверждает доступ к боевому провайдеру и доступность в продакшене.

Песочница провайдера ConnectID

Песочница провайдера ConnectID использует тестовые банки и отделена от имитации в песочнице Didit. Если для вашей интеграции настроен доступ к песочнице провайдера, передайте authorisation_server_id выбранного банка в начальный endpoint ConnectID. Используйте ID, который возвращает селектор банков ConnectID; не отправляйте URL банка или произвольного эмитента. Если поле не указано, выбирается тестовый банк по умолчанию. Это поле относится только к ConnectID и не меняет запрашиваемые атрибуты личности. Начальный набор запрашивает имя, фамилию и дату рождения. Следуйте возвращённому next_action, чтобы пройти аутентификацию, затем получите или опросите результат верификации. Только завершённый результат со статусом «одобрена» подтверждает успешную верификацию; возврат в ваше приложение этого не подтверждает. ConnectID остаётся в статусе Скоро в продакшене, пока завершаются онбординг и сертификация.

Доступность и цены

Покрытие endpoint’ов и активация кошелька в продакшене не связаны между собой. Страница справочника API для кошелька может существовать, при этом аутентификация в продакшн-среде через него недоступна. Перед внедрением боевого сценария проверьте покрытие кошелька по странам и его статус в продакшене. Опубликованные тарифы и доступность см. в разделе цены на цифровые ID-кошельки. Верификация через кошелёк тарифицируется отдельно от захвата документов.

Выбор интеграции

Используйте эти API, если хотите сами управлять интерфейсом и логикой приложения. Используйте Sessions API, если нужны размещённый сценарий верификации Didit, правила сценария и настроенные резервные шаги. Оба подхода всё равно требуют процесса аутентификации и согласия, предусмотренного кошельком.
Последнее изменение 7 ноября 2026 г.