> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Didit 전화번호 인증의 모든 위험 코드(HIGH_RISK_PHONE_NUMBER, VOIP_NUMBER_DETECTED, DISPOSABLE_NUMBER_DETECTED, 차단 목록, OTP 한도 등)에 대한 레퍼런스입니다.

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

## 개요

경고는 `PHONE` 기능으로 태그가 지정됩니다. `GET /v3/session/{sessionId}/decision/`의 `phone_verifications[].warnings[]` 아래에 표시되며 표준 [경고 객체](https://docs.didit.me/ko/reference/data-models.md#경고-객체) 형태(`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](https://docs.didit.me/ko/management-api/lists/overview.md)를 통해 관리되는 차단 목록에 포함되어 있거나, 차단 목록에 등록된 세션과 일치합니다.

전송 업체의 사기 방지 계층이 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](https://docs.didit.me/ko/management-api/lists/overview.md)를 통해 생성된 전화번호 허용 목록에 있는 번호는 차단된 전송으로 인해 자동으로 거부되지 않습니다. 해당 단계는 **검토 중**으로 이동하고, 경고에는 `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](https://docs.didit.me/ko/management-api/lists/overview.md)를 통해 생성된 차단 목록에 포함되어 있거나 차단 목록에 등록된 세션과 일치합니다. 자동으로 거부됩니다. `additional_data`: `{ blocklisted_session_id, blocklisted_session_number, api_service }`(순수 목록 일치의 경우 모두 `null`). |
| `PHONE_NUMBER_IN_ALLOWLIST` | `information` | 해당 번호가 다른 세션과 일치하지만 [Lists API](https://docs.didit.me/ko/management-api/lists/overview.md)를 통해 생성된 허용 목록에 포함되어 있어 중복 전화번호 작업이 건너뛰어집니다. `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`를 발생시킵니다. 전체 일치 스키마는 [전화번호 인증 보고서](https://docs.didit.me/ko/core-technology/phone-verification/report-phone-verification.md#세션-간-일치-항목)를 참조하십시오.

## 예시

VoIP 번호에서 차단된 전송(`HIGH_RISK_PHONE_NUMBER`)이 발생하고 `voip_number_action`이 `REVIEW`로 설정된 경우의 예시:

```json theme={null}
{
  "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"
    }
  ]
}
```

## 경고 유형

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

## 관련 문서

* [전화번호 인증 개요](https://docs.didit.me/ko/core-technology/phone-verification/overview.md) — 기능 동작, 요금, 지원되는 채널.
* [전화번호 인증 보고서](https://docs.didit.me/ko/core-technology/phone-verification/report-phone-verification.md) — `lifecycle[]` 및 `matches[]`를 포함한 전체 응답 구조.
* [데이터 모델 — 전화번호 인증](https://docs.didit.me/ko/reference/data-models.md#전화번호-인증) — 표준 필드별 스키마.
* [Management API — 목록](https://docs.didit.me/ko/management-api/lists/overview.md) — `PHONE_NUMBER_IN_BLOCKLIST`에서 사용되는 전화번호 차단 목록 관리.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.