workflow_id не нужно.
Ваш бэкенд запускает верификацию и получает её результат, а ваш интерфейс проводит человека через обязательную аутентификацию в кошельке.
Интеграция через API по-прежнему требует, чтобы человек прошёл аутентификацию и подтвердил передачу своих данных личности.
Без этого взаимодействия верифицировать человека, отправив только его личный идентификатор, нельзя.
Как работает верификация
- Ваш бэкенд проверяет каталог кошельков, затем вызывает эндпоинт запуска доступного кошелька, используя API-ключ вашего приложения.
- Didit возвращает справочный номер верификации и действие, которое должен выполнить человек.
- Ваше приложение открывает страницу аутентификации или показывает инструкции кошелька по подтверждению.
- Человек проходит аутентификацию в своём кошельке.
- Ваш бэкенд получает подтверждённый результат и обрабатывает уведомления о завершении.
Интеграция на стороне бэкенда
Используйте Список цифровых 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.
Повторите запрос через указанное в заголовке количество секунд, чтобы получить завершённый результат.
Регистрация адреса возврата
Кошельки с перенаправлением возвращают человека в ваше приложение после аутентификации. Зарегистрируйте точное имя хоста до запуска верификации: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 остаётся в статусе Скоро в продакшене, пока завершаются онбординг и сертификация.