전화번호 인증 경고 및 위험 코드

전화번호 인증 기능은 OTP 플로우 또는 번호 자체에서 위험 신호(알려진 유해 번호, VoIP 또는 일회용 번호, OTP 시도 횟수 제한 초과, 다른 사용자의 세션과의 일치 등)가 감지될 때마다 경고를 생성합니다. 이 페이지에서는 각 코드와 트리거 조건, 그리고 워크플로 응답을 구성하는 방법을 설명합니다.

개요

경고는 PHONE 기능으로 태그가 지정됩니다. GET /v3/session/{sessionId}/decision/의 phone_verifications[].warnings[] 아래에 표시되며 표준 경고 객체 형태(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) 또는 OTP 전송 2회 초과(phone_max_retries)이며, 둘 다 워크플로 노드별로 조정할 수 있습니다. 독립형 전화번호 API에서는 3회의 코드 시도가 허용됩니다.
PHONE_NUMBER_IN_BLOCKLIST: 번호가 Lists API를 통해 관리되는 차단 목록에 포함되어 있거나, 차단 목록에 등록된 세션과 일치합니다.

전송 업체의 사기 방지 계층이 OTP 전송을 거부하는(Blocked 전송) HIGH_RISK_PHONE_NUMBER는 기본적으로 거부되지만 더 이상 무조건적인 것은 아닙니다. 아래의 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) 후 해당 단계는 VERIFICATION_CODE_ATTEMPTS_EXCEEDED와 함께 Declined로 완료됩니다. 독립형 전화번호 API는 인증 건당 3회의 코드 시도를 허용합니다.
전송 시도 — 기본값은 총 2회 전송(phone_max_retries)입니다(최초 전송 1회 + 재전송 1회). 추가 전송 요청 시 단계가 완료되며 VERIFICATION_CODE_ATTEMPTS_EXCEEDED가 발생합니다.
OTP 유효 기간 — 대기 중인 OTP는 최초 전송 후 5분 동안 유효하며, 재시도하더라도 유효 기간이 연장되지 않습니다.

두 상한 모두 워크플로 노드별로 조정할 수 있습니다. 이러한 상한과 무관하게, 전송 제공업체의 사기 방지 레이어가 전송을 완전히 차단할 수도 있으며(사유: repeated_attempts, suspicious 또는 spam), 이 경우 시도 횟수 경고가 아닌 HIGH_RISK_PHONE_NUMBER가 발생합니다.

생성되는 경고

Tag	`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, 그리고 session(동일한 번호를 가진 다른 세션, 상태 무관) 또는 list_entry(배열 맨 앞에 추가되는 합성 차단 목록 일치 항목)인 source가 포함됩니다. 현재 번호가 전화번호 허용 목록에 있는 경우 Didit은 일치 증거를 보존하지만 중복 전화번호 작업을 적용하는 대신 PHONE_NUMBER_IN_ALLOWLIST를 발생시킵니다. 전체 일치 스키마는 전화번호 인증 보고서를 참조하십시오.

예시

VoIP 번호에서 차단된 전송(HIGH_RISK_PHONE_NUMBER)이 발생하고 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"
    }
  ]
}

경고 유형

애플리케이션 설정에 따라 각 위험에 심각도가 할당됩니다. 심각도는 세 가지 범주로 나뉩니다.

인증

인증

모니터링

플랫폼

전화번호 인증 경고 및 위험 코드

개요

자동 거부 조건

구성 가능한 위험

차단된 전송

인증 시도 횟수 제한

생성되는 경고

세션 간 일치 항목

예시

경고 유형

관련 문서

​개요

​자동 거부 조건

​구성 가능한 위험

​차단된 전송

​인증 시도 횟수 제한

​생성되는 경고

​세션 간 일치 항목

​예시

​경고 유형

​관련 문서

개요

자동 거부 조건

구성 가능한 위험

차단된 전송

인증 시도 횟수 제한

생성되는 경고

세션 간 일치 항목

예시

경고 유형

관련 문서