config внутри каждого элемента массива features для POST /v3/workflows/ и PATCH /v3/workflows/{settings_uuid}/.
features. Передавайте функции строго в порядке их выполнения.
Выбор движка, который выполняет функцию (собственного движка Didit или стороннего провайдера), не входит в число полей config, перечисленных ниже. Это настраивается в консоли в разделе Marketplace, который сам задаёт
provider_key и fallback_to_native в объекте config функции.Правила валидации
OCRпо умолчанию использует все поддерживаемые страны и типы документов, еслиconfig.documents_allowedне передан, равенnullили{}. Если вы передаёте собственный объектdocuments_allowed, он должен содержать хотя бы одну допустимую страну и хотя бы один включённый тип документа. Каждая конфигурация документа может задаватьsides:1для захвата только лицевой стороны или2для захвата лицевой и оборотной стороны.QUESTIONNAIREтребуетconfig.questionnaire_uuid.KYB_DOCUMENTSтребуетconfig.kyb_required_document_groups.SIGNATUREвозвращает ошибкуqes_not_availableприsignature_level: "qes", пока квалифицированные подписи не станут доступны, и ошибкуaes_not_availableдля нового шага сsignature_level: "aes", покаsignature_availability.aesимеет значениеfalseв сценарии. Документы для этой функции должны существовать к моменту создания сессии: еслиsignature_documents_sourceравенworkflow, шагу нужны документы, загруженные в консоли; шаг без документов может остаться черновиком, но не может быть переведён в работу. Если указаноsession, каждый запрос на создание должен передаватьsign.documents.FACE_MATCHдолжен идти послеOCRв запросах для простых сценариев.NFCиDATABASE_VALIDATIONтребуютOCR, если они присутствуют в одном сценарии. ПередAMLдолжна стоять одна из функций:OCR,KYB_REGISTRYилиDOCUMENT_AI. Если перед ним стоит толькоDOCUMENT_AI, полеfull_name, по которому выполняется скрининг, должно быть заполняемым: либо из поля Document AI, уже имеющего ключfull_name(оно сопоставляется автоматически), либо из явной записиconfig.aml_field_sources(см. AML).- Подфункции KYB, такие как
KYB_DOCUMENTSиKYB_KEY_PEOPLE, требуют, чтобыKYB_REGISTRYстоял раньше в сценарии. - Сценарий является либо KYC-сценарием для физических лиц, либо KYB-сценарием для компаний, но не может быть и тем и другим. Сценарий, который использует любую функцию KYB (
KYB_REGISTRY,KYB_DOCUMENTS,KYB_KEY_PEOPLE), может сочетать её только сAML,DOCUMENT_AI,QUESTIONNAIRE,PHONE_VERIFICATION,EMAIL_VERIFICATION,IP_ANALYSISиSIGNATURE. Он не может включать функции только для физических лиц, такие какOCR,LIVENESS,FACE_MATCH,NFC,PROOF_OF_ADDRESS,DATABASE_VALIDATIONилиAGE_ESTIMATION, а KYC-сценарий не может включать функции KYB. В KYB-сценарииDOCUMENT_AIсравнивает любое поле с пометкойis_full_nameс проверенной компанией, а не с человеком. Чтобы проверить людей, стоящих за компанией, создайте отдельный KYC-сценарий и укажите его в функцииKYB_KEY_PEOPLEчерезkyb_ubo_verification_workflow,kyb_officer_verification_workflowилиkyb_shareholder_verification_workflow. - Поля действий принимают
DECLINE,REVIEWилиNO_ACTION, если в описании поля не указано иное. - Поля оценок и порогов принимают числа от
0до100, если не указан более узкий диапазон.
Общие правила статусов
Каждая функция поддерживает необязательный массивstatus_rules. Используйте его, чтобы переопределить статус функции, когда выполняется условие для поля.
Пример выше читается так:
kyc.extra_fields.profession нечётко совпадает с Soft. Engineer с минимальной оценкой 80, и тогда статус функции устанавливается в Declined.
Для верификации личности указывайте извлечённые значения из extra_fields, например kyc.extra_fields.profession, даты действия классов водительского удостоверения, такие как kyc.extra_fields.dl_class_code_b_from и kyc.extra_fields.dl_class_code_b_to, или коды ограничений и сведений по каждому классу, например kyc.extra_fields.dl_class_code_b_notes (столбец 12 британских водительских удостоверений). Эти значения берутся из объекта extra_fields результата OCR; они не входят в expected_details.
Поля
dl_class_code_*_from и dl_class_code_*_to всегда содержат либо корректную дату в формате ISO, либо отсутствуют в extra_fields. Didit никогда не возвращает нечитаемый текст OCR в поле даты. Если ячейку в таблице классов не удалось прочитать, поле пропускается, а не передаётся как необработанная строка. Поэтому для маршрутизации дат классов, которые не удалось прочитать, используйте оператор is_empty, а не исходите из того, что поле всегда присутствует.value_type: "relative_date" со значением в виде объекта { "direction": "past" | "future", "amount": number, "unit": "days" | "months" | "years" }. Например, operator: "less_than" с { "direction": "past", "amount": 3, "unit": "years" } совпадает с датами, которые были более чем на три года раньше сегодняшней даты.
Сравнение с конкретным шагом
Граф сценария может запускать одну и ту же функцию несколько раз, например три шага верификации личности. Приvalue_type: "field" добавьте к значению суффикс @<node_id>, чтобы считать значение с одного конкретного шага.
Указанный узел должен быть шагом функции, который всегда выполняется до шага правила на каждом пути, ведущем к шагу правила, либо самим шагом правила.
Значение без суффикса считывается с шага, к которому относится правило.
kyc.full_name этого шага нечётко совпадает с полным именем, извлечённым на шаге ocr_1, с минимальной оценкой 80, и тогда статус функции устанавливается в Declined.
В консоли селектор переменных показывает каждый подходящий шаг по его номеру на холсте и сохраняет суффикс за вас.
OCR / Верификация личности
Значение функции:OCR.
Проверка живости документа настраивается шестью порогами
document_liveness_* выше, а не полями действий для каждого сигнала. portrait_replacement_action, printed_copy_action и screen_capture_action являются настройками уровня аккаунта и не принимаются в конфигурации функций сценария: API удаляет неизвестные ключи конфигурации при сохранении, поэтому их отправка там не имеет эффекта. Для каждого сигнала есть порог отклонения и порог проверки по шкале от 0 до 100, где более высокая оценка означает, что документ с большей вероятностью является подлинным.Методы по странам
methods задаётся по коду страны ISO 3166-1 alpha-3. Для каждой страны указывается до трёх объектов методов. Всё, что вы не укажете, получает значение по умолчанию.
wallet.on_failure может принимать значения fallback_to_document, decline или retry. retry (только для кошелька, когда захват документа отключён для страны) оставляет пользователю, чей вход не завершился на шаге кошелька, возможность попробовать снова. Сессия никогда не отклоняется по этой причине и остаётся открытой, пока пользователь не завершит шаг или она не истечёт. Переключатели id_lookup принимают только fallback_to_document или decline.
Чтобы не показывать документы на первом экране и предлагать их, только если кошелёк или поиск не сработали, задайте document.fallback_only. В примере используется Финляндия, где сначала идёт Finnish Trust Network, а захват документа служит запасным вариантом. Для Финляндии также нужно включить типы документов в documents_allowed (например, паспорт и ID-карту), чтобы у запасного варианта были документы для предложения.
available в текущем каталоге, поэтому эта конфигурация сохраняется как написано. Блок кошелька намеренно опущен в этом примере: конфигурация кошелька сохраняется только для страны, где каталог помечает его как available. Значение wallet.enabled: true в любой другой стране отклоняется и отменяет всё сохранение, включая конфигурацию поиска. Если каталог помечает кошелёк как available в нужной вам стране, добавьте его для этой страны:
Правила валидации, которые API применяет при сохранении:
- Неизвестный код страны, неизвестный ключ внутри страны или неизвестный ключ внутри метода отклоняются. Ничего не отбрасывается молча.
- Страна, в которой не включён ни один метод, отклоняется: там никто не сможет пройти верификацию.
- Кошелёк или проверка по реестру могут перейти к съёмке документа только тогда, когда съёмка документа включена для этой страны. Значение
fallback_to_documentв стране, гдеdocument.enabledравноfalse, приводит к отказу во время выполнения, потому что переходить некуда. document.fallback_only: trueотклоняется с HTTP 400, еслиdocument.enabledне равноtrueили ни один кошелёк и ни одна проверка по реестру в этой стране не переходит к съёмке документа.
methods, изучите каталог возможностей: во вкладке Страны консоли или с помощью MCP-инструмента didit_workflow_get_id_verification_methods_catalog. Поведение, покрытие и биллинг описаны на странице Методы верификации личности.
NFC / ePassport
Значение функции:NFC.
Liveness
Значение функции:LIVENESS.
Сравнение лиц
Значение функции:FACE_MATCH.
Оценка возраста
Значение функции:AGE_ESTIMATION.
Проверка телефона
Значение функции:PHONE_VERIFICATION.
Проверка телефона отключена, пока организация не выполнит первое пополнение баланса.
Обогащение данными о телефоне – необязательная надстройка. Когда
phone_enrichment_enabled имеет значение true, каждая завершенная проверка телефона обогащается данными о телефоне, и за каждый запрос взимается плата в размере $0.05 сверх стандартной стоимости проверки телефона. Действия на основе оценки срабатывают только после того, как оценка обогащения станет доступна; действия по индексу доверия, типу телефона и переносу номера применяются сразу после запуска обогащения.Проверка социального следа является второй, отдельной надстройкой. Когда phone_social_enabled имеет значение true, каждая завершенная проверка телефона также сообщает, на каких онлайн-платформах зарегистрирован номер: мессенджеры, социальные сети, электронная коммерция и профессиональные сервисы. За нее взимается $0.05 за запрос. Ее можно включить с phone_enrichment_enabled или без него: две надстройки оплачиваются и тарифицируются независимо. Запрос, который не находит номер ни на одной из охватываемых платформ, является корректным и оплачиваемым результатом и запускает phone_no_social_presence_action. Чтобы ветвить сценарий в графе сценария по результату, используйте phone.social_profiles_registered (количество платформ, на которых зарегистрирован номер).Проверка электронной почты
Значение функции:EMAIL_VERIFICATION.
Обогащение email-данными является необязательной дополнительной опцией. Когда
email_enrichment_enabled имеет значение true, каждая завершённая проверка электронной почты обогащается email-данными, и за каждый запрос взимается плата $0.05 сверх стандартной стоимости проверки электронной почты. Действие на основе оценки применяется, как только оценка обогащения становится доступна; действия при утечках применяются сразу после запуска обогащения.Проверка цифрового следа в соцсетях является второй, отдельной дополнительной опцией. Когда email_social_enabled имеет значение true, каждая завершённая проверка электронной почты также сообщает, на каких онлайн-платформах зарегистрирован адрес: почтовые сервисы, социальные сети, профессиональные, e-commerce и развлекательные сервисы. За это взимается $0.05 за запрос. Её можно включить как с email_enrichment_enabled, так и без него: обе дополнительные опции тарифицируются и оплачиваются независимо друг от друга. Если проверка не находит адрес ни на одной из охватываемых платформ, это корректный и оплачиваемый результат, и он запускает email_no_social_presence_action. Используйте email.social_profiles_registered (количество платформ, на которых зарегистрирован адрес), чтобы ветвить сценарий по результату в графе сценария.Проверка по базам данных
Значение функции:DATABASE_VALIDATION.
Пример:
400, в ответе указывается этот сервис и причина, а сценарий не сохраняется.
Это относится к ID, которого нет в каталоге, к ID, принадлежащему другой стране, к сервису, который пока недоступен, и к сервису, доступному только через отдельный эндпоинт POST /v3/database-validation/.
Сервис, входные данные которого не предоставляет ни один предыдущий шаг, отклоняется так же, а в ответе перечисляются недостающие входные данные.
Сервис, который уже есть в сохранённом сценарии, но больше не может быть выполнен, удаляется при повторном сохранении.
Например, этот сценарий для Аргентины считывает номер DNI и пол из Верификации личности и проверяет их по RENAPER без селфи:
arg_renaper после шага LIVENESS, чтобы дополнительно сравнить селфи с фотографией, которая хранится в RENAPER.
Оценку совпадения лиц и порог для RENAPER см. в разделе RENAPER.
Верификация банка
Значение функции:BANK_VERIFICATION.
Пользователь верифицирует банковский счёт, и имя владельца счёта, которое сообщает банк, сравнивается с данными личности, установленными предыдущим шагом сценария. Пользователь делает это одним из двух способов: вход в банк (open_banking), когда он входит в свой банк, или проверка счёта (account_lookup), когда он вводит реквизиты счёта, а банк подтверждает имя владельца. bank_method_order и methods каждой страны определяют, какие способы предлагает страна и какой из них идёт первым; см. Способы верификации банка. Шаг формирует доказательства: оценку совпадения имени владельца, сравнение, которое её дало, и коды причин. Ключи bank_*_action превращают эти доказательства в статус.
Два условия определяют, выполняет ли узел вообще какое-либо действие. bank_countries является белым списком, поэтому пустая карта не предлагает ни одного банка и не выполняет проверку. Владельцу нужно с чем сравниваться: поставьте перед узлом шаг OCR, DATABASE_VALIDATION или QUESTIONNAIRE, передайте expected_details при создании сессии или сопоставьте поля самостоятельно через bank_field_sources. Если ни одного из этого нет, принадлежность может быть только unknown, и решает это bank_reference_identity_missing_action.
Верификация банка всё ещё внедряется, поэтому узел
BANK_VERIFICATION принимается только для аккаунта, где он включён. В остальных случаях сохранение отклоняется, и система сообщает об этом. Какой маршрут выполняет шаг, здесь тоже не настраивается: это пара provider_key и fallback_to_native, которую за вас задаёт Маркетплейс в консоли.Подключение счёта
Когда пользователь не может верифицировать
Пользователь всегда может продолжить без банка, и шаг никогда не оставляет его в тупике. См. Когда человек не может верифицировать банк.
Что для сессии означает продолжение, определяют
bank_unsupported_action, bank_attempts_exhausted_action или bank_skipped_action в зависимости от причины, по которой пользователь продолжил, если только предыдущая попытка уже не определила шаг: см. Действия по вердикту.
Сравнение владельца счёта
Проверка счёта
Эти ключи применяются только к проверке счёта. Для входа в банк сохраняется обработка близких совпадений и собственныйbank_max_attempts.
Финансовые данные
bank_expected_currencies работает с одним лишь согласием ownership по умолчанию. Остальные три ключа читают реальные финансовые данные, поэтому каждому из них нужна соответствующая область согласия в bank_scopes, без неё сохранение отклоняется.
Что сохраняется
Действия по решению
Каждый ключ здесь принимаетDECLINE, REVIEW или NO_ACTION, если он не помечен как ограниченный. Если вы не передали ключ или передали null, применяется значение по умолчанию, указанное ниже. Ничто, что не является подтверждением владения, не одобряется по умолчанию, и отклонение возможно только при наличии явного доказательства против пользователя.
Дополнительные настройки
Эти ключи необязательны. Каждый ключ действия принимаетDECLINE, REVIEW или NO_ACTION.
Пример объекта
config для аккаунта, где включена Bank Verification и выбранный маршрут охватывает указанную страну:
AML
Значение функции:AML.
Для скрининга физического лица (KYC) используйте следующие поля:
Для скрининга компании (KYB) используйте следующие поля:
Проверка сущности, извлечённой шагом Document AI
Шаг AML обычно берёт данные о проверяемом лице из шагаOCR (физическое лицо) или из шага KYB_REGISTRY (компания). В сценарии, единственный шаг извлечения которого - DOCUMENT_AI (нестандартизированные документы, например налоговая справка или учредительный документ), ни одного из этих шагов нет, поэтому сценарий должен явно указать, откуда берётся каждый входной параметр скрининга.
Пример: скрининг компании, названной в мексиканской acta constitutiva, в сценарии нет ни одного документа, удостоверяющего личность:
Анализ устройства и IP
Значение функции:IP_ANALYSIS.
Пример:
recovered_device_action отдельно от duplicated_device_action, если хотите отслеживать устройства, идентифицированные при восстановлении отпечатка с высокой степенью уверенности, прежде чем автоматически их отклонять. Это полезно на этапе внедрения: совпадения восстановленных устройств предназначены для выявления мошеннических групп, но их всё равно нужно откалибровать по вашему собственному трафику.
Верификация местоположения
Значение функции:GEOLOCATION.
Проверяет, где находится человек во время верификации, по позиции устройства или по местоположению IP-адреса подключения, сравнивая её с разрешёнными и заблокированными зонами, местоположением IP и адресом в документе.
Как ведёт себя этот шаг, см. в разделе Верификация местоположения, а поля решения описаны в его отчёте.
Если нужно измерять расстояние до адреса в документе, размещайте шаг после Верификации личности или Подтверждения адреса: расстояние измеряется, только если адрес уже указан в системе.
Если geolocation_position_source не задан, расстояние до местоположения по IP требует шага Анализ устройства и IP в том же сценарии.
Все ключи необязательны: шаг с пустым config запрашивает у устройства позицию с точностью до 250 м, не старше 120 секунд, даёт человеку 3 попытки и не применяет правил для зон.
У каждого результата проверки есть свой ключ действия. Если ключ действия не задан, он получает значение по умолчанию из выбранного geolocation_preset, а если пресет не выбран, то значение по умолчанию для этого ключа, указанное ниже.
Неопределённое местоположение или отказ в его предоставлении по умолчанию приводят к REVIEW, но никогда к DECLINE, потому что отказ в разрешении или широкий радиус не являются доказательством мошенничества.
Явно заданное действие всегда имеет приоритет над пресетом.
Повторно использованный запрос (LOCATION_REPLAY_DETECTED) и неуспешная аттестация устройства (LOCATION_INTEGRITY_FAILED) всегда приводят к отклонению и не имеют ключа действия.
Формы областей
Каждый элементgeolocation_areas имеет id (от 1 до 64 символов из A-Z a-z 0-9 _ -, уникальный в списке), необязательную label (до 80 символов), type со значением allowed или blocked и kind, который определяет форму.
Список содержит не более 50 областей и требует хотя бы одной области
allowed, пока is_geolocation_geofencing_enabled равно true.
geolocation_areas и geolocation_geofencing_by_country нельзя передавать вместе, а geolocation_refusal_path: "end_session" требует, чтобы geolocation_permission_denied_action было REVIEW или DECLINE.
API отклоняет область, которая никогда не сможет совпасть, например регион страны без опубликованных границ, и не сохраняет её.
Пример:
Подтверждение адреса
Значение функции:PROOF_OF_ADDRESS.
Анкеты
Значение функции:QUESTIONNAIRE.
Реестр KYB
Значение функции:KYB_REGISTRY.
kyb_registry_fields_config сопоставляет каждый настраиваемый ключ поля с {"enabled": bool, "required": bool}. enabled: false скрывает поле, enabled: true, required: false показывает его как необязательное, а enabled: true, required: true делает его обязательным при отправке. company_name, country_code и region всегда показываются и обязательны, их нельзя настроить. Если объект опущен, равен null или {}, применяется значение по умолчанию: обязательно только incorporation_date, все остальные поля необязательны.
registration_number, incorporation_date, legal_address, vat_number, alternative_names, tax_number, company_type, legal_entity_identifier, location_of_registration, nature_of_business, registered_capital_amount, registered_capital_currency, website, email, phone, control_scheme. Поведение для конечного пользователя см. в разделе настраиваемые поля формы реестра, а о том, как проверяются vat_number и tax_number, см. в разделе проверка VAT и налогового номера.
Документы KYB
Значение функции:KYB_DOCUMENTS.
Ключевые лица KYB
Значение функции:KYB_KEY_PEOPLE.
Document AI
Значение функции:DOCUMENT_AI.
Запрашивает у пользователя один или несколько документов и извлекает заданные вами поля с помощью модели компьютерного зрения. Каждое настроенное поле становится значением для ветвления document_ai.<key>, а результатом шага является document_ai.status.
Каждый элемент
document_ai_documents является документом:
Каждый элемент
fields документа является полем:
Пример:
Электронная подпись
Значение функции:SIGNATURE.
Позволяет верифицированному лицу или ключевым лицам компании подписывать документы на уровне Simple (по умолчанию) или Advanced (AES). Размещайте этот шаг после шагов, которые проверяют подписанта: Верификация личности и Проверка электронной почты или телефона для одноразового кода. См. Электронная подпись.
Поля в документе сценария задаются в редакторе шаблонов консоли. Для документов сессии передавайте поля в
sign.documents[].fields, а значения полей api.<key> передавайте в sign.field_values. См. Создание сессии.
Пример для документов, которые передаются с каждой сессией: