Перейти к основному содержанию
Используйте эти поля config внутри каждого элемента массива features для POST /v3/workflows/ и PATCH /v3/workflows/{settings_uuid}/.
API сценариев v3 строит линейный сценарий на основе узлов из упорядоченного массива 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 или ни один кошелёк и ни одна проверка по реестру в этой стране не переходит к съёмке документа.
Текущая реализация в тестовой среде применяет id_lookup.response_fields к результатам сравнения, необязательному полю «пол» и сохраняемым портретам из реестра. Обязательные поля идентификации остаются частью записи о верификации. Это не гарантия того, что каждый промежуточный payload провайдера исключается из обработки. Развёртывание этого изменения в продакшн не проверялось. Перед тем как полагаться на выбор полей для требований к хранению данных, убедитесь в поведении в целевой среде.
Перед тем как писать 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. Пример:
database_validation_countries определяет, выполняет ли этот шаг какие-либо действия. Функция DATABASE_VALIDATION, сохранённая без этого поля, принимается, но проверки при этом не выполняются вовсе, поэтому всегда передавайте хотя бы одну страну с хотя бы одним ID сервиса.
Если сервис не может быть выполнен на этом шаге, запрос отклоняется с кодом 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 и выбранный маршрут охватывает указанную страну:
Именно bank_countries активирует этот шаг, и проверяется он по маршруту, на котором выполняется узел, а не по общему списку. Страна, в которой этот маршрут не может установить владение счётом, отклоняется при сохранении, и её название указано в ошибке. Читайте ошибку, а не предполагайте, что страна принята и будет пропущена во время выполнения.

AML

Значение функции: AML. Для скрининга физического лица (KYC) используйте следующие поля: Для скрининга компании (KYB) используйте следующие поля:

Проверка сущности, извлечённой шагом Document AI

Шаг AML обычно берёт данные о проверяемом лице из шага OCR (физическое лицо) или из шага KYB_REGISTRY (компания). В сценарии, единственный шаг извлечения которого - DOCUMENT_AI (нестандартизированные документы, например налоговая справка или учредительный документ), ни одного из этих шагов нет, поэтому сценарий должен явно указать, откуда берётся каждый входной параметр скрининга. Пример: скрининг компании, названной в мексиканской acta constitutiva, в сценарии нет ни одного документа, удостоверяющего личность:
Если перед ним нет шагов OCR и KYB_REGISTRY, шаг AML должен иметь возможность заполнить full_name: без имени поиск у провайдера невозможен. Сценарий, который ничего не сопоставляет или сопоставляет ключ Document AI, который ни один предыдущий шаг не извлекает, отклоняется при сохранении, а не сохраняется с пустым скринингом. Точность AML напрямую зависит от количества передаваемых идентификаторов: скрининг только по имени даёт большой объём ложных срабатываний.

Анализ устройства и 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. См. Создание сессии. Пример для документов, которые передаются с каждой сессией:
Последнее изменение 7 ноября 2026 г.