Проверка телефона: предупреждения и коды риска

Функция Проверка телефона генерирует предупреждения каждый раз, когда срабатывает сигнал риска в процессе OTP или в отношении самого номера: заведомо неблагонадёжный номер, VoIP или одноразовый номер, превышение лимита попыток ввода OTP или совпадение с сессией другого пользователя. На этой странице перечислены все коды, условия их срабатывания и способы настройки реакции сценария.

Обзор

Предупреждения помечаются функцией PHONE. Они отображаются в массиве phone_verifications[].warnings[] в ответе GET /v3/session/{sessionId}/decision/ и имеют стандартную структуру объекта предупреждения (feature, risk, additional_data, log_type, short_description, long_description, node_id). Каждое предупреждение также записывается в журнал сессии и отображается в Business Console в разделе Phone. Некоторые предупреждения служат триггерами безусловного автоматического отклонения — они всегда переводят статус функции в Declined. Другие соотносятся с настраиваемым действием (DECLINE, REVIEW или NO_ACTION, в зависимости от настройки), заданным в настройках сценария, поэтому один и тот же код риска может приводить к отклонению в одном сценарии и лишь привлекать внимание в другом.

Условия автоматического отклонения

Следующие предупреждения всегда отклоняют шаг Проверка телефона независимо от конфигурации и всегда содержат log_type: "error":

VERIFICATION_CODE_ATTEMPTS_EXCEEDED — пользователь исчерпал лимит попыток OTP: по умолчанию 2 неверных ввода кода (phone_max_check_attempts) или более 2 отправок OTP (phone_max_retries), оба параметра настраиваются для каждого узла сценария. Автономный API проверки телефона допускает 3 попытки ввода кода.
PHONE_NUMBER_IN_BLOCKLIST — номер находится в вашем списке блокировки, управляемом через Lists API, или совпадает с сессией, внесённой в список блокировки.

HIGH_RISK_PHONE_NUMBER — отказ антифрод-системы провайдера доставки отправить OTP (отправка Blocked) — отклоняет по умолчанию, но больше не является безусловным: см. high_risk_phone_action ниже.

Настраиваемые риски

Каждый из следующих рисков сопоставлен с настройкой сценария, для которой можно настроить значение DECLINE, REVIEW или NO_ACTION (по умолчанию — предупреждение фиксируется без влияния на статус). Настроенное действие также определяет log_type предупреждения: DECLINE → error, REVIEW → warning, NO_ACTION → information.

Настройка	Код риска	Срабатывает, когда
`voip_number_action`	`VOIP_NUMBER_DETECTED`	Тип линии определяется как `voip`, `isp` или `vpn`.
`disposable_number_action`	`DISPOSABLE_NUMBER_DETECTED`	При проверке номер определяется как принадлежащий поставщику временных или одноразовых номеров.
`duplicated_phone_number_action`	`DUPLICATED_PHONE_NUMBER`	Номер совпадает с другой сессией в любом статусе, принадлежащей другому конечному пользователю. Проверка пропускается, если номер находится в списке разрешений.

Обнаружение дубликатов работает в рамках вашего приложения по всем проверкам телефонов в KYC, KYB и автономном API и группирует сессии по vendor_data: сессии с одинаковым vendor_data считаются принадлежащими одному конечному пользователю и исключаются из результатов совпадений. Если оставить vendor_data пустым, каждая сессия будет считаться отдельным пользователем.

Заблокированные отправки

HIGH_RISK_PHONE_NUMBER следует тому же принципу с более узким набором вариантов, поскольку отправка, отклонённая провайдером, не может быть одобрена:

Настройка	Код риска	Срабатывает, когда
`high_risk_phone_action`	`HIGH_RISK_PHONE_NUMBER`	Антифрод-система провайдера доставки отказалась отправить OTP (отправка `Blocked`). Принимает только `DECLINE` или `REVIEW`, по умолчанию — `DECLINE`.

Этот параметр применяется только тогда, когда каждая блокировка высокого риска на шаге содержит в additional_data.risk_factors ровно ["device_attribute"] — сигнал провайдера о том, что «устройство выглядит подозрительным», который может срабатывать на обычных мобильных номерах. Любой другой фактор риска, любая комбинация, лишь включающая device_attribute, или блокировка вообще без факторов риска приводят к отклонению независимо от настройки. Причина блокировки (repeated_attempts, suspicious или spam) передаётся в отдельном поле additional_data.blocked_reason. Независимо от настройки, номер из списка разрешённых номеров телефонов, созданного через Lists API, никогда не отклоняется автоматически из-за заблокированной отправки: шаг переходит в статус На проверке, предупреждение получает log_type: "warning", а additional_data.phone_number_in_allowlist принимает значение true.

Лимиты попыток верификации

Функция «Проверка телефона» применяет жёсткое ограничение на количество попыток ввода OTP для предотвращения злоупотреблений:

Попытки ввода кода — По умолчанию 2 неверные попытки ввода (phone_max_check_attempts), после чего шаг завершается со статусом Declined с ошибкой VERIFICATION_CODE_ATTEMPTS_EXCEEDED. Отдельный API проверки телефона разрешает 3 попытки ввода кода за верификацию.
Попытки отправки — По умолчанию 2 отправки в сумме (phone_max_retries): начальная отправка плюс одна повторная отправка. Следующий запрос на отправку завершает шаг и вызывает VERIFICATION_CODE_ATTEMPTS_EXCEEDED.
Срок действия OTP — OTP, ожидающий подтверждения, действителен в течение 5 минут с момента первой отправки; повторные попытки не продлевают это окно.

Оба лимита настраиваются для каждого узла сценария. Независимо от этих лимитов, антифрод-система провайдера доставки может полностью заблокировать отправку (причина repeated_attempts, suspicious или spam) — это вызовет HIGH_RISK_PHONE_NUMBER, а не предупреждение о попытках.

Генерируемые предупреждения

Тег	`log_type`	Описание
`VERIFICATION_CODE_ATTEMPTS_EXCEEDED`	`error` (всегда)	Пользователь превысил лимит ввода кода OTP или лимит отправок. Автоматически отклоняется.
`HIGH_RISK_PHONE_NUMBER`	Соответствует `high_risk_phone_action` или `warning`, если номер в белом списке	Провайдер доставки заблокировал отправку OTP. По умолчанию отклоняется; установите `high_risk_phone_action` в `REVIEW`, чтобы направлять блокировку исключительно по сигналам устройства в статус «на проверке» (см. Заблокированные отправки). Номер из белого списка телефонов также переходит в статус «на проверке». `additional_data`: `{ blocked_reason, risk_factors, phone_number_in_allowlist? }`.
`PHONE_NUMBER_IN_BLOCKLIST`	`error` (всегда)	Номер находится в списке блокировки, созданном через Lists API, или совпадает с сессией, внесённой в список блокировки. Автоматически отклоняется. `additional_data`: `{ blocklisted_session_id, blocklisted_session_number, api_service }` (все `null` при совпадении только со списком).
`PHONE_NUMBER_IN_ALLOWLIST`	`information`	Номер совпал с другими сессиями, но находится в белом списке, созданном через Lists API, поэтому действия для дублирующихся номеров пропускаются. `additional_data`: `{ phone_number }`.
`DISPOSABLE_NUMBER_DETECTED`	Соответствует `disposable_number_action`	Номер принадлежит провайдеру временных или одноразовых номеров, часто используемому для уклонения от отслеживания.
`VOIP_NUMBER_DETECTED`	Соответствует `voip_number_action`	Номер относится к линии типа `voip`, `isp` или `vpn`, а не к стандартной мобильной или фиксированной линии.
`DUPLICATED_PHONE_NUMBER`	Соответствует `duplicated_phone_number_action`	Номер совпадает с другой сессией — в любом статусе — принадлежащей другому конечному пользователю (группировка по `vendor_data`). `additional_data`: `{ duplicated_session_id, duplicated_session_number, api_service }`.

Совпадения между сессиями

Когда номер обнаруживается в других сессиях или в вашем списке блокировки, эти совпадения также отображаются в phone_verifications[].matches[] (не более 5 записей). Каждое совпадение содержит session_id, session_number, vendor_data, verification_date, phone_number, status, is_blocklisted, api_service и source со значением session (другая сессия с тем же номером, в любом статусе) или list_entry (синтетическое совпадение со списком блокировки, добавленное в начало массива). Если текущий номер находится в вашем белом списке телефонов, Didit сохраняет данные о совпадении, но выдаёт PHONE_NUMBER_IN_ALLOWLIST вместо применения действия для дублирующихся номеров. Полную схему совпадений см. в разделе Отчёт о проверке телефона.

Пример

Заблокированная отправка (HIGH_RISK_PHONE_NUMBER) для номера VoIP с параметром voip_number_action, настроенным на REVIEW:

{
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "HIGH_RISK_PHONE_NUMBER",
      "additional_data": { "blocked_reason": "suspicious" },
      "log_type": "error",
      "short_description": "High risk phone number",
      "long_description": "The system detected that the phone number is a high risk phone number, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "VoIP number detected",
      "long_description": "The system detected that the phone number is a VoIP number, which is not allowed.",
      "node_id": "feature_phone_1"
    }
  ]
}

Типы предупреждений

Каждому риску присваивается уровень критичности на основе настроек вашего приложения. Уровни критичности делятся на три категории:

Связанные материалы

Обзор Проверки телефона — поведение функции, цены, поддерживаемые каналы.
Отчёт о проверке телефона — полная структура ответа, включая lifecycle[] и matches[].
Модели данных — проверка телефона — каноническая схема полей.
Management API — Списки — управление списком блокировки номеров, используемым PHONE_NUMBER_IN_BLOCKLIST.

Аутентификация

Верификация

Мониторинг

Платформа

Проверка телефона: предупреждения и коды риска

Обзор

Условия автоматического отклонения

Настраиваемые риски

Заблокированные отправки

Лимиты попыток верификации

Генерируемые предупреждения

Совпадения между сессиями

Пример

Типы предупреждений

Связанные материалы

​Обзор

​Условия автоматического отклонения

​Настраиваемые риски

​Заблокированные отправки

​Лимиты попыток верификации

​Генерируемые предупреждения

​Совпадения между сессиями

​Пример

​Типы предупреждений

​Связанные материалы

Обзор

Условия автоматического отклонения

Настраиваемые риски

Заблокированные отправки

Лимиты попыток верификации

Генерируемые предупреждения

Совпадения между сессиями

Пример

Типы предупреждений

Связанные материалы