> ## 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.

# 워크플로 기능 설정 API 레퍼런스

> features 배열로 단순 선형 워크플로를 만들 때 Didit의 POST 및 PATCH /v3/workflows/가 허용하는 모든 설정 필드를 설명합니다.

[`POST /v3/workflows/`](https://docs.didit.me/ko/management-api/workflows/create)와 [`PATCH /v3/workflows/{settings_uuid}/`](https://docs.didit.me/ko/management-api/workflows/update)의 `features` 배열 각 항목 안에서 다음 `config` 필드를 사용합니다.

```json theme={null}
{
  "workflow_label": "Standard KYC",
  "features": [
    {
      "feature": "OCR",
      "config": {
        "documents_allowed": {
          "USA": {
            "DL": {
              "enabled": 1,
              "sides": 2
            }
          }
        }
      }
    }
  ]
}
```

v3 워크플로 API는 순서가 지정된 `features` 배열로 선형 노드 기반 워크플로를 구성합니다. 기능은 실행 순서대로 정확히 보내야 합니다.

> [!NOTE]
>
> 기능을 실행하는 엔진(Didit 자체 엔진 또는 제3자 제공업체)은 아래 config 필드에 포함되지 않습니다. 이는 콘솔의 [Marketplace](https://docs.didit.me/ko/console/marketplace.md)에서 관리하며, 해당 기능의 `config` 객체에 `provider_key`와 `fallback_to_native`를 자동으로 설정합니다.

## 검증 규칙

* `config.documents_allowed`가 생략되거나 `null` 또는 `{}`이면 `OCR`은 지원되는 모든 국가와 문서 유형을 기본값으로 사용합니다. 사용자 지정 `documents_allowed` 객체를 보내는 경우, 유효한 국가를 하나 이상, 활성화된 문서 유형을 하나 이상 포함해야 합니다. 각 문서 구성에서 `sides`를 `1`로 설정하면 앞면만, `2`로 설정하면 앞면과 뒷면을 촬영합니다.
* `QUESTIONNAIRE`에는 `config.questionnaire_uuid`가 필요합니다.
* `KYB_DOCUMENTS`에는 `config.kyb_required_document_groups`가 필요합니다.
* `SIGNATURE`는 적격 서명을 사용할 수 있게 될 때까지 `signature_level: "qes"`를 `qes_not_available` 오류와 함께 거부합니다. 또한 워크플로에서 `signature_availability.aes`가 `false`인 동안에는 새 단계에서 `signature_level: "aes"`를 `aes_not_available` 오류와 함께 거부합니다. 세션을 생성할 때 서명 문서가 있어야 합니다. `signature_documents_source`가 `workflow`로 설정된 경우 해당 단계에는 콘솔에서 업로드한 문서가 필요하며, 문서가 없는 단계는 초안 상태로 둘 수 있지만 프로덕션 환경으로 전환할 수 없습니다. `session`으로 설정된 경우 모든 생성 호출에 `sign.documents`를 포함해야 합니다.
* 간단한 워크플로 요청에서 `FACE_MATCH`는 `OCR` 뒤에 와야 합니다.
* `NFC`와 `DATABASE_VALIDATION`이 같은 워크플로에 포함되면 `OCR`이 필요합니다. `AML`의 앞에는 `OCR`, `KYB_REGISTRY`, `DOCUMENT_AI` 중 하나가 와야 합니다. 앞에 `DOCUMENT_AI`만 있는 경우 검사 대상 `full_name`을 입력할 수 있어야 합니다. 즉, `full_name` 키가 이미 설정된 상위 Document AI 필드에서 가져오거나(자동으로 매핑됨), 명시적인 `config.aml_field_sources` 항목에서 가져와야 합니다([AML](#aml) 참고).
* `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE` 같은 KYB 하위 기능은 워크플로에서 앞서 `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`과 같이 개인 전용 기능은 포함할 수 없으며, 개인 워크플로에는 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` 배열을 지원합니다. 필드 조건이 일치할 때 기능 상태를 재정의하려면 이 배열을 사용하세요.

```json theme={null}
{
  "status_rules": [
    {
      "field": "kyc.issuing_state",
      "operator": "in",
      "value": ["VEN", "IRN"],
      "status": "In Review",
      "value_type": "literal"
    },
    {
      "field": "kyc.extra_fields.profession",
      "operator": "fuzzy_match",
      "value": "Soft. Engineer",
      "score": 80,
      "status": "Declined",
      "value_type": "literal"
    },
    {
      "field": "kyc.extra_fields.dl_class_code_b_to",
      "operator": "less_than",
      "value": "2030-01-01",
      "status": "In Review",
      "value_type": "literal"
    },
    {
      "field": "kyc.extra_fields.dl_class_code_b_from",
      "operator": "less_than",
      "value": { "direction": "past", "amount": 3, "unit": "years" },
      "status": "Declined",
      "value_type": "relative_date"
    }
  ]
}
```

| 필드 | 유형 | 설명 |
| - | - | - |
| `field` | string | 확인할 필드 경로입니다. 예: `kyc.issuing_state` 또는 `kyc.document_type`. |
| `operator` | string | `equals`, `not_equals`, `greater_than`, `greater_than_or_equals`, `less_than`, `less_than_or_equals`, `contains`, `not_contains`, `in`, `not_in`, `is_empty`, `is_not_empty`, `regex`, `fuzzy_match` 중 하나입니다. |
| `value` | any | 비교 값입니다. 값이 필요 없는 연산자의 경우 생략하거나 `null`을 전송합니다. |
| `status` | string | `Approved`, `Declined`, `In Review`, `No Action` 중 하나입니다. |
| `value_type` | string | 선택 사항입니다. 기본값은 `literal`입니다. 다른 필드와 비교하려면 `field`를, 실행 시점에 Didit 목록 UUID를 확인하려면 `list`를, 날짜 필드를 오늘을 기준으로 한 일정 기간 전후와 비교하려면 `relative_date`를 사용합니다. |
| `score` | number | `fuzzy_match`에 필요합니다. `0`에서 `100` 사이의 최소 유사도 점수입니다. 계산된 유사도가 이 값보다 크거나 같을 때 규칙이 일치합니다(`similarity >= score`). 예를 들어 `Software Engineer`는 유사도가 `80` 이상이면 `Soft. Engineer`와 일치할 수 있습니다. |

위 예시는 다음과 같이 읽습니다. `kyc.extra_fields.profession`이 최소 점수 `80`으로 `Soft. Engineer`와 퍼지 일치하면 → 기능 상태를 `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번 열)가 있습니다. 이 값은 OCR 결과의 `extra_fields` 객체에서 가져오며, `expected_details`의 일부가 아닙니다.

> [!NOTE]
>
> `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" }`를 함께 사용하면 오늘부터 3년보다 오래된 날짜와 일치합니다.

### 특정 단계와 비교

그래프 워크플로는 같은 기능을 여러 번 실행할 수 있습니다. 예를 들어 신분증 인증 단계를 세 개 둘 수 있습니다.
`value_type: "field"`를 사용할 때는 값 뒤에 `@<node_id>`를 붙여 특정 단계에서 값을 읽을 수 있습니다. 참조하는 노드는 모든 경로에서 규칙이 속한 단계보다 항상 먼저 실행되는 기능 단계이거나, 규칙이 속한 단계 자체여야 합니다. 접미사가 없는 값은 규칙이 속한 단계에서 읽습니다.

```json theme={null}
{
  "status_rules": [
    {
      "field": "kyc.full_name",
      "operator": "fuzzy_match",
      "value": "kyc.full_name@ocr_1",
      "value_type": "field",
      "score": 80,
      "status": "Declined"
    }
  ]
}
```

세 번째 신분증 인증 단계에 설정된 이 규칙은 다음과 같이 읽습니다. 이 단계의 `kyc.full_name`이 `ocr_1` 단계가 읽은 성명과 최소 점수 `80`으로 퍼지 일치하면 → 기능 상태를 `Declined`로 설정합니다.
콘솔에서는 변수 선택기가 캔버스의 단계 번호와 함께 해당 단계를 나열하며, 접미사는 자동으로 저장됩니다.

## OCR / 신분증 인증

기능 값: `OCR`.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `documents_allowed` | object | 선택 사항입니다. 생략하거나, `null`을 보내거나, `{}`를 보내면 지원되는 모든 국가와 문서 유형을 허용합니다. 허용되는 문서를 제한하고 싶을 때만 ISO3 국가 코드별 문서 유형 설정을 보냅니다. 사용자 정의 문서 중 최소 하나는 `enabled: 1`이어야 합니다. 문서 설정에는 앞면만 촬영하는 `sides: 1` 또는 앞뒤를 모두 촬영하는 `sides: 2`를 포함할 수 있습니다. 문서 유형에는 `P`, `ID`, `DL`, `RP`, `HIC`, `TC`, `SSC` 및 국가별로 지원되는 기타 값이 포함됩니다. |
| `methods` | object | 각 국가에서 사용할 수 있는 세 가지 [신분증 인증 방식](https://docs.didit.me/ko/core-technology/id-verification/verification-methods.md)을 지정합니다: 문서 촬영, 정부 또는 기타 공신력 있는 출처를 통한 비문서 조회, 디지털 신원 지갑. 키, 국가 또는 국가 내 방식을 생략하면 해당 국가는 문서 촬영만 사용합니다. 모든 방식과 지갑은 기능 카탈로그에서 해당 국가에 사용 가능으로 표시되어야 하며, 그렇지 않으면 저장이 거부됩니다. 아래 [국가별 방식](#국가별-방법)을 참조하세요. |
| `document_blur_fields_by_country` | object | 문서 이미지에서 흐리게 처리해 가릴 필드 이름을 ISO3 국가 코드별로 지정합니다. |
| `image_capture_methods_allowed` | string\[] | 허용되는 촬영 방식입니다. 값에는 `CAMERA_SCAN`과 `UPLOAD`가 포함됩니다. |
| `duplicated_user_action` | action | 중복 사용자에 대한 작업입니다. |
| `is_age_restrictions_enabled` | boolean | 최소 및 최대 연령 확인을 활성화합니다. |
| `age_restrictions_by_country` | object | ISO3 국가 코드별 연령 설정입니다. `minimum_age`, 선택 사항인 `maximum_age`, 선택 사항인 `states`를 포함합니다. |
| `minimum_age` | integer | 전역 최소 연령으로, `1`에서 `120` 사이입니다. |
| `minimum_age_action` | action | 사용자가 `minimum_age`보다 어릴 때의 작업입니다. |
| `maximum_age` | integer | 전역 최대 연령으로, `1`에서 `120` 사이입니다. |
| `maximum_age_action` | action | 사용자가 `maximum_age`를 초과할 때의 작업입니다. |
| `expiration_date_not_detected_action` | action | 문서 만료일이 없을 때의 작업입니다. |
| `invalid_code_action` | action | 바코드 또는 기계 판독 코드가 유효하지 않을 때의 작업입니다. |
| `invalid_mrz_action` | action | MRZ가 유효하지 않을 때의 작업입니다. |
| `inconsistent_data_action` | action | 추출된 문서 필드 간에 충돌이 있을 때의 작업입니다. |
| `invalid_validation_action` | action | 문서 검증이 실패할 때의 작업입니다. |
| `expected_details_mismatch_action` | action | 예상되는 사용자 정보가 문서와 일치하지 않을 때의 작업입니다. |
| `image_too_blurry_action` | action | 흐릿한 문서 이미지에 대한 작업입니다. |
| `image_too_dark_action` | action | 어두운 문서 이미지에 대한 작업입니다. |
| `image_too_bright_action` | action | 과다 노출된 문서 이미지에 대한 작업입니다. |
| `unparsed_address_action` | action | 문서 주소를 파싱할 수 없을 때의 작업입니다. |
| `address_validation_enabled` | boolean | 이 단계에서 읽은 주소(신분증에 인쇄된 주소)를 우편 참조 데이터와 대조해 검증합니다. 주소가 실제로 존재하는지 확인하고 정규화하며, 주소를 사람과 연결하지 않습니다. 결과는 결정 내 이 단계의 `address_validation` 객체입니다. **검증된 주소당 \$0.10이 과금됩니다**. 검증을 실행할 수 없는 경우(`unavailable`)는 무료입니다. 기본값은 꺼짐입니다. |
| `address_not_verified_action` | action | 주소 검증이 주소를 건물 단위까지 확인하지 못할 때의 작업입니다(`ADDRESS_NOT_VERIFIED`: `partially_verified` 또는 `not_verified`). `address_validation_enabled`가 켜져 있을 때에만 적용됩니다. 기본값은 `NO_ACTION`이며, 이는 경고만 기록합니다. |
| `document_or_personal_number_format_mismatch_action` | action | 문서 번호 또는 개인 번호의 형식이 예상 패턴과 일치하지 않을 때의 작업입니다. |
| `critical_field_occlusion_action` | action | 가림 검사에서 중요한 인쇄 필드(신원 번호, 이름, 생년월일 또는 만료일 중 하나)가 촬영된 문서에서 물리적으로 가려졌다고 보고할 때의 작업입니다. 신원 번호를 가리는 것은 촬영 품질 문제가 아니라 변조 신호이므로 기본값은 `REVIEW`입니다. 가려진 필드에서 읽은 값은 어떤 경우든 추출 결과에서 제외됩니다. 가려진 문서가 검토자에게 절대 전달되면 안 되는 경우 `DECLINE`으로 올리세요. |
| `document_without_portrait_action` | action | 인식된 문서 유형에 어느 면에도 인물 사진이 없을 때의 작업입니다(일부 거주 허가증, 건강 카드, 등록 증명서 및 카탈로그에 알려진 기타 사진 없는 문서군). 기본값은 `REVIEW`입니다. 워크플로의 신원 확인 기준이 얼굴 대조인 경우 `DECLINE`을 고려하세요. |
| `is_document_selfie_portrait_match_enabled` | boolean | 문서 인물 사진과 셀피의 비교를 활성화합니다. |
| `document_selfie_portrait_match_decline_threshold` | integer | 문서 인물 사진과 셀피 일치에 대한 거부 임계값입니다. |
| `document_selfie_portrait_match_review_threshold` | integer | 문서 인물 사진과 셀피 일치에 대한 검토 임계값입니다. |
| `document_selfie_face_search_enabled` | boolean | 문서 촬영 중 찍은 셀피에 [얼굴 검색 1:N](https://docs.didit.me/ko/core-technology/face-search/overview.md#문서-촬영-중-캡처된-셀피)을 실행합니다(`is_document_selfie_portrait_match_enabled` 필요). 얼굴 차단 목록 및 이전에 인증된 사용자와 대조합니다. 셀피는 비교만 하며 템플릿은 절대 저장되지 않습니다. 기본값은 켜짐입니다. `false`로 설정하면 검색을 건너뛰며, 문서 셀피 중복 얼굴 작업은 처리할 대상이 없게 됩니다. 라이브니스 단계의 `face_search_enabled: false`도 검색을 건너뛰는데, 이 옵트아웃은 세션의 모든 셀피에 적용되기 때문입니다. |
| `document_selfie_duplicated_face_action` | action | 문서 촬영 셀피가 이 애플리케이션에서 이미 인증된 사용자의 얼굴과 일치하거나 일치할 가능성이 있을 때의 판정입니다. 기본값은 `NO_ACTION`입니다. |
| `document_selfie_duplicated_face_name_mismatch_action` | action | 문서 촬영 셀피가 다른 이름으로 이미 인증된 사용자와 일치할 때의 판정입니다. `document_selfie_duplicated_face_action`을 상향만 할 수 있습니다. 기본값은 `REVIEW`입니다. |
| `document_selfie_duplicated_face_document_mismatch_action` | action | 문서 촬영 셀피가 신분증에 다른 생년월일로 이미 인증된 사용자와 일치할 때의 판정입니다. 다른 문서나 갱신된 문서를 가진 동일 인물은 플래그되지 않습니다. `document_selfie_duplicated_face_action`을 상향만 할 수 있습니다. 기본값은 `REVIEW`입니다. |
| `id_verification_name_match_score_threshold` | integer | 여러 신분증 인증에 걸친 이름 일치 임계값입니다. |
| `id_verification_max_retry_attempts` | integer | 신분증 인증의 재시도 한도이며, `2`부터 `5`까지 설정할 수 있습니다. |
| `id_document_quality_threshold` | integer | 문서 이미지가 수락되려면 도달해야 하는 최소 촬영 품질 점수(`0`부터 `100`까지)입니다. 품질 검사는 항상 실행되며, 이 임계값만 설정할 수 있습니다. 기본값은 `20`입니다. 이 값은 흐림, 움직임, 판독할 수 없는 텍스트가 있는 저하되었거나 경계에 있는 촬영본은 거부하고, 판독 가능한 문서는 통과하도록 조정되어 있습니다. 더 엄격한 촬영 요건이 필요하면 값을 높이십시오. 콘솔에서는 이 값이 체감 기준 슬라이더에 표시되며, 기본값 `20`은 균형 잡힌 50%로 나타납니다. |
| `cross_org_fraud_document_action` | action | 네트워크의 다른 조직이 이 문서를 사기로 표시한 경우의 판정입니다. |
| `document_audio_recording_enabled` | boolean | 문서 촬영 중 마이크로 음성을 녹음하여 검토자가 세션을 들을 수 있도록 합니다. 기본적으로 꺼져 있습니다. |
| `document_liveness_portrait_replace_decline_threshold` | integer | 얼굴 사진 교체 점수(`0`부터 `100`까지, 높을수록 진짜일 가능성이 큼)가 이 값보다 낮으면 세션이 거부됩니다. 기본값은 `35`입니다. 자세한 내용은 [문서 라이브니스 임계값](https://docs.didit.me/ko/core-technology/id-verification/warnings-id-verification.md#문서-라이브니스-임계값-구성)을 참조하십시오. |
| `document_liveness_portrait_replace_review_threshold` | integer | 얼굴 사진 교체 점수가 이 값보다 낮으면, 이미 거부되지 않은 경우 세션이 검토 중으로 전환됩니다. `100`으로 설정하면 거의 모든 세션이 보류됩니다. 기본값은 `70`입니다. 자세한 내용은 [문서 라이브니스 임계값](https://docs.didit.me/ko/core-technology/id-verification/warnings-id-verification.md#문서-라이브니스-임계값-구성)을 참조하십시오. |
| `document_liveness_printed_copy_decline_threshold` | integer | 인쇄본 점수(`0`부터 `100`까지, 높을수록 진짜일 가능성이 큼)가 이 값보다 낮으면 세션이 거부됩니다. 기본값은 `35`입니다. 자세한 내용은 [문서 라이브니스 임계값](https://docs.didit.me/ko/core-technology/id-verification/warnings-id-verification.md#문서-라이브니스-임계값-구성)을 참조하십시오. |
| `document_liveness_printed_copy_review_threshold` | integer | 인쇄본 점수가 이 값보다 낮으면, 이미 거부되지 않은 경우 세션이 검토 중으로 전환됩니다. `100`으로 설정하면 거의 모든 세션이 보류됩니다. 기본값은 `77`입니다. 자세한 내용은 [문서 라이브니스 임계값](https://docs.didit.me/ko/core-technology/id-verification/warnings-id-verification.md#문서-라이브니스-임계값-구성)을 참조하십시오. |
| `document_liveness_screen_replay_decline_threshold` | integer | 화면 캡처 점수(`0`부터 `100`까지, 높을수록 진짜일 가능성이 큼)가 이 값보다 낮으면 세션이 거부됩니다. 기본값은 `30`입니다. 자세한 내용은 [문서 라이브니스 임계값](https://docs.didit.me/ko/core-technology/id-verification/warnings-id-verification.md#문서-라이브니스-임계값-구성)을 참조하십시오. |
| `document_liveness_screen_replay_review_threshold` | integer | 화면 캡처 점수가 이 값보다 낮으면, 이미 거부되지 않은 경우 세션이 검토 중으로 전환됩니다. `100`으로 설정하면 거의 모든 세션이 보류됩니다. 기본값은 `70`입니다. 자세한 내용은 [문서 라이브니스 임계값](https://docs.didit.me/ko/core-technology/id-verification/warnings-id-verification.md#문서-라이브니스-임계값-구성)을 참조하십시오. |
| `id_verification_injection_attack_action` | action | 문서 또는 신분증 조회를 위해 찍은 셀피가 기기 자체 카메라로 촬영된 것이 아니라 주입된 경우(`INJECTION_ATTACK_DETECTED`)의 판정입니다. 여기에는 소프트웨어 가상 카메라, 페이지나 브라우저 자동화가 생성한 카메라 피드, 후킹된 카메라, 앱에 연결된 계측 도구가 포함됩니다. 값은 `DECLINE`, `REVIEW`, `NO_ACTION`입니다. 기본값은 `DECLINE`입니다. 실제 사람이 만들어낼 수 있는 신호로는 이 판정이 절대 발생하지 않습니다. 라이브니스와 얼굴 대조에서는 위험도가 대신 `frame_injection_action`을 따릅니다. |
| `image_quality_too_low_action` | action | 문서 이미지의 전반적인 품질이 기준에 미치지 못할 때의 판정입니다. |
| `is_image_capture_review_screen_enabled` | boolean | 문서를 촬영할 때마다 사용자에게 검토 화면을 보여 주어, 제출 전에 사진을 다시 찍을 수 있도록 합니다. 기본적으로 꺼져 있습니다. |
| `is_ocr_id_verification_data_review_enabled` | boolean | 단계가 완료되기 전에 사용자가 추출된 신원 데이터를 검토하고 수정할 수 있도록 합니다. 기본적으로 꺼져 있습니다. 수정 내용은 `ocr_id_verification_data_review_critical_fields`를 기준으로 평가되며, 불일치가 있으면 그에 따라 중요 판정 또는 경미 판정이 적용됩니다. 워크플로에 NFC가 포함되어 있어도 검토는 실행됩니다. 이후의 칩 읽기가 그 결과를 대체할 뿐입니다. |
| `ocr_id_verification_data_review_critical_fields` | string\[] | 사용자가 OCR 결과를 수정할 때 어떤 추출 신원 필드를 중요 필드로 볼지 정합니다. 이렇게 하면 불일치가 경미 판정이 아닌 중요 판정을 받습니다. 형식: `["first_name" \| "last_name" \| "date_of_birth" \| ...]`. |
| `ocr_id_verification_data_review_critical_mismatch_action` | restricted action | 사용자의 수정 내용이 중요 필드에서 OCR과 일치하지 않을 때의 판정입니다. |
| `ocr_id_verification_data_review_minor_mismatch_action` | action | 사용자의 수정 내용이 중요하지 않은 필드에서 OCR과 일치하지 않을 때의 판정입니다. |
| `status_rules` | array | 선택 사항인 맞춤 상태 규칙입니다. |

> [!NOTE]
>
> 문서 라이브니스는 위의 여섯 개 `document_liveness_*` 임계값으로 설정하며, 신호별 판정 필드로는 설정하지 않습니다. `portrait_replacement_action`, `printed_copy_action`, `screen_capture_action`은 계정 수준 설정이므로 워크플로 기능 설정에서는 허용되지 않습니다. API는 저장할 때 알 수 없는 설정 키를 제거하므로, 여기에 보내도 아무 효과가 없습니다. 각 신호에는 `0`부터 `100`까지의 척도에 따른 거부 임계값과 검토 임계값이 있으며, 점수가 높을수록 문서가 진짜일 가능성이 높습니다.

예시:

```json theme={null}
{
  "feature": "OCR",
  "config": {
    "documents_allowed": {
      "USA": {
        "DL": {
          "enabled": 1,
          "sides": 2
        }
      }
    },
    "duplicated_user_action": "REVIEW",
    "image_capture_methods_allowed": ["CAMERA_SCAN", "UPLOAD"]
  }
}
```

### 국가별 방법

`methods`는 [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) 국가 코드를 키로 사용합니다. 각 국가에는 최대 세 개의 방법 객체를 포함할 수 있으며, 생략한 항목은 기본값을 따릅니다.

```json theme={null}
{
  "feature": "OCR",
  "config": {
    "methods": {
      "ZAF": {
        "document": { "enabled": true },
        "id_lookup": {
          "enabled": true,
          "max_attempts": 2,
          "skip_liveness_and_face_match": true,
          "on_partial_match": "fallback_to_document",
          "on_no_match": "fallback_to_document",
          "on_provider_error": "fallback_to_document"
        },
        "wallet": { "enabled": false, "providers": [], "on_failure": "fallback_to_document" }
      },
      "DNK": {
        "document": { "enabled": true },
        "id_lookup": { "enabled": true, "on_no_match": "decline" }
      }
    }
  }
}
```

`wallet.on_failure`는 `fallback_to_document`, `decline`, `retry` 중 하나입니다. `retry`(지갑 전용이며, 해당 국가에서 문서 촬영이 꺼져 있어야 합니다)는 지갑 단계에서 로그인을 완료하지 못한 사용자가 다시 시도할 수 있도록 합니다. 이 경우 세션은 거부되지 않으며, 사용자가 완료하거나 세션이 만료될 때까지 열려 있습니다. id\_lookup 스위치는 `fallback_to_document` 또는 `decline`만 사용할 수 있습니다.

지갑이나 조회가 성공하지 못했을 때에만 문서를 제공하고 첫 화면에서는 문서를 숨기려면 `document.fallback_only`를 설정하십시오. 예시는 핀란드를 사용합니다. 핀란드 신뢰 네트워크가 먼저 표시되고, 문서 촬영이 대체 수단입니다. 대체 수단에서 제공할 문서가 있도록, 핀란드에서는 `documents_allowed`에서 문서 유형(예: 여권과 신분증)도 활성화해야 합니다.

```json theme={null}
{
  "FIN": {
    "document": { "enabled": true, "fallback_only": true },
    "wallet": { "enabled": true, "providers": ["ftn"], "on_failure": "fallback_to_document" }
  }
}
```

위의 두 조회는 현재 카탈로그에서 모두 `available`이므로 해당 설정은 그대로 저장됩니다. 이 예시에서 지갑 블록은 의도적으로 제외되었습니다. 지갑은 카탈로그에서 `available`로 표시된 국가에서만 저장할 수 있으며, 그 밖의 국가에서 `wallet.enabled: true`를 설정하면 거부되어 조회 설정을 포함한 전체 저장이 실패합니다. 지갑이 `available`로 표시된 국가라면 해당 국가에 지갑을 추가하십시오:

```json theme={null}
{
  "DNK": {
    "document": { "enabled": true },
    "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" }
  }
}
```

| 키 | 유형 | 기본값 | 설명 |
| - | - | - | - |
| `<ISO3>.document.enabled` | boolean | `true` | 이 국가에서 촬영한 문서를 허용할지 여부입니다. 허용되는 문서 종류는 `documents_allowed`에서 계속 관리합니다. |
| `<ISO3>.document.fallback_only` | boolean | `false` | 문서 촬영은 계속 활성화하되 첫 화면에는 제공하지 않습니다. 사용자는 해당 국가의 지갑 또는 신분증 조회로 시작하며, 지갑 로그인이 실패하거나 취소되거나 시간 초과되었거나 조회 결과가 일치하지 않은 경우(`on_failure`, `on_partial_match`, `on_no_match`, `on_provider_error` 스위치가 `fallback_to_document`로 설정된 경우)에만 문서 촬영으로 이동합니다. 지갑이 하나뿐이면 사용자는 바로 그 지갑으로 이동합니다. 지갑이 없으면 지갑 또는 조회 옵션이 문서 촬영과 나란히 표시됩니다. `document.enabled`가 `true`이고 해당 국가의 지갑 또는 신분증 조회 중 하나 이상이 문서 촬영으로 대체되도록 설정되지 않으면 HTTP 400으로 거부됩니다. |
| `<ISO3>.id_lookup.enabled` | boolean | `false` | 이 국가의 정부 또는 기타 공인 출처를 대상으로 하는 문서 없는 조회를 제공합니다. 카탈로그에서 해당 국가의 출처가 `available`로 표시되지 않으면 거부됩니다. |
| `<ISO3>.id_lookup.max_attempts` | integer | `1` | `1`부터 `5`까지입니다. 대체 스위치가 작동하기 전에 사용자가 받을 수 있는 **응답받은** 조회 횟수입니다. 클라이언트 측 형식 검사를 통과하지 못한 숫자는 레지스트리에 전달되지 않으므로 집계되거나 과금되지 않습니다. |
| `<ISO3>.id_lookup.skip_liveness_and_face_match` | boolean | `true` | 초상 사진을 반환하는 레지스트리와 일치한 후 워크플로 자체의 라이브니스 감지 및 얼굴 대조 단계를 건너뜁니다. 조회 과정에서 이미 셀피에 대해 패시브 라이브니스 검사를 수행했고, 그 셀피를 해당 초상 사진과 대조했기 때문입니다. 초상 사진을 반환하지 않는 출처에서는 이 스위치가 의미가 없으므로 저장 시 `false`로 정규화됩니다. |
| `<ISO3>.id_lookup.on_partial_match` | `fallback_to_document` \| `decline` | `fallback_to_document` | 레지스트리가 응답했지만 일부 필드가 일치하지 않을 때의 처리 방식입니다. |
| `<ISO3>.id_lookup.on_no_match` | `fallback_to_document` \| `decline` | `fallback_to_document` | 레지스트리가 응답했지만 일치하는 레코드가 없을 때의 처리 방식입니다. |
| `<ISO3>.id_lookup.on_provider_error` | `fallback_to_document` \| `decline` | `fallback_to_document` | 레지스트리에 연결할 수 없을 때의 처리 방식입니다. 과금되지 않습니다. |
| `<ISO3>.id_lookup.response_fields` | string\[] \| null | `null` | 출처 응답 필드 키의 선택적 하위 집합입니다. 알 수 없는 키는 거부되며, 출처의 필수 필드는 항상 다시 추가되므로 저장된 값은 항상 유효한 선택입니다. 현재 스테이징 구현은 이 선택을 비교 결과, 선택 사항인 성별, 보관된 레지스트리 초상 사진에 적용합니다. 필수 신원 필드는 유지됩니다. 아래의 롤아웃 및 보존 안내를 참고하십시오. |
| `<ISO3>.wallet.enabled` | boolean | `false` | 이 국가에서 디지털 신분증 지갑 로그인을 제공합니다. |
| `<ISO3>.wallet.providers` | string\[] | `[]` | 이 국가가 허용하는 카탈로그 지갑 ID입니다. 허용 목록이며 순위가 아닙니다. 전송한 순서는 카탈로그 순서로 정규화됩니다. `enabled`가 `true`이면 지갑이 최소 하나 필요합니다. 해당 국가에서 제공되지 않거나 아직 출시 예정인 지갑은 거부됩니다. |
| `<ISO3>.wallet.on_failure` | `fallback_to_document` \| `decline` \| `retry` | `fallback_to_document` | 로그인이 취소되거나 시간 초과되거나 실패했을 때의 처리 방식입니다. `retry`는 사용자를 지갑 단계에 머물게 하여 다시 시도하도록 합니다(지갑에만 적용). `document.fallback_only`와 함께 설정하면 거부됩니다. |

API가 저장 시 적용하는 검증은 다음과 같습니다.

* 알 수 없는 국가 코드, 국가 내의 알 수 없는 키, 방법 내의 알 수 없는 키는 거부됩니다. 아무것도 조용히 삭제되지 않습니다.
* 어떤 방법도 활성화되지 않은 국가는 거부됩니다. 그곳의 누구도 인증할 수 없기 때문입니다.
* 지갑이나 조회는 해당 국가에서 문서 촬영이 활성화된 경우에만 문서 촬영으로 대체될 수 있습니다. `document.enabled`가 `false`인 국가에서 `fallback_to_document`를 설정하면 대체할 곳이 없으므로 런타임에 거부됩니다.
* `document.fallback_only: true`는 `document.enabled`가 `true`이고 해당 국가의 지갑 또는 신분증 조회 중 하나 이상이 문서 촬영으로 대체되도록 설정되지 않으면 HTTP 400으로 거부됩니다.

> [!WARNING]
>
> 현재 스테이징 구현은 `id_lookup.response_fields`를 비교 결과, 선택 사항인 성별, 보관된 레지스트리 초상 사진에 적용합니다. 필수 신원 필드는 인증 기록의 일부로 계속 남습니다. 이는 모든 중간 제공자 페이로드가 처리에서 제외된다는 보장이 아닙니다. 이 변경의 프로덕션 롤아웃은 검증되지 않았습니다. 보존 요건에 필드 선택을 의존하기 전에 대상 환경에서 동작을 확인하십시오.

`methods`를 작성하기 전에 기능 카탈로그를 확인하십시오. 콘솔의 **국가** 탭에서 보거나 [`didit_workflow_get_id_verification_methods_catalog`](https://docs.didit.me/ko/integration/mcp/tools) MCP 도구로 확인할 수 있습니다. 동작, 적용 범위, 과금은 [신분증 인증 방법](https://docs.didit.me/ko/core-technology/id-verification/verification-methods.md)에서 확인하십시오.

## NFC / 전자여권

기능 값: `NFC`.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `allow_nfc_skip` | boolean | 문서가 칩 판독을 지원하는 경우 사용자가 NFC를 건너뛸 수 있도록 허용합니다. |
| `skip_nfc_action` | 작업 | 사용자가 NFC를 건너뛸 때의 작업입니다. |
| `unverified_chip_action` | 작업 | 칩 검증이 실패할 때의 작업입니다. |
| `trust_anchor_missing_action` | 작업 | 칩의 데이터 그룹 해시는 온전하지만 발급 국가의 CSCA 신뢰 앵커가 로드되지 않아 인증서 체인을 검증할 수 없을 때의 판정입니다. |
| `jpki_request_attributes` | boolean | 일본 마이넘버 카드([JPKI](https://docs.didit.me/ko/core-technology/nfc-verification/overview.md#일본-마이넘버카드-jpki), 네이티브 SDK 전용): 서명 인증서도 읽습니다. 이 인증서는 카드의 서명 PIN이 필요하며, 소유자의 성명, 생년월일, 성별 및 주소를 담고 있어 신분증 인증 데이터와 비교합니다. 기본값은 `true`입니다. `false`로 설정하면 사용자 인증서(4자리 PIN)만 읽습니다. 이 인증서는 카드의 소지와 PIN을 알고 있음을 증명하지만 소유자 정보는 포함하지 않습니다. |
| `jpki_certificate_invalid_action` | 작업 | 마이넘버 카드 인증서가 JPKI 인증 기관까지 체인으로 연결되지 않거나, 유효 기간을 벗어났거나, 요청한 유형의 카드 인증서가 아닐 때의 판정입니다(`JPKI_CERTIFICATE_INVALID`). 기본값은 `DECLINE`입니다. |
| `jpki_signature_invalid_action` | 작업 | 마이넘버 카드가 일회용 챌린지에 대해 생성한 서명을 검증하지 못해 카드를 소지하고 PIN을 알고 있음을 증명할 수 없을 때의 판정입니다(`JPKI_SIGNATURE_INVALID`). 기본값은 `DECLINE`입니다. |
| `jpki_certificate_revoked_action` | 작업 | 폐기 확인에서 마이넘버 카드 인증서가 폐기된 것으로 보고될 때의 판정입니다(`JPKI_CERTIFICATE_REVOKED`). 기본값은 `DECLINE`입니다. |
| `jpki_revocation_unchecked_action` | 작업 | 마이넘버 카드는 검증되었으나 폐기 여부에 대한 응답을 받을 수 없어 폐기된 카드를 배제할 수 없을 때의 판정입니다(`JPKI_REVOCATION_UNCHECKED`). 기본값은 `REVIEW`입니다. |
| `jpki_inconsistent_data_action` | 작업 | 마이넘버 카드 서명 인증서의 성명, 생년월일, 성별 또는 주소가 같은 카드의 신분증 인증 데이터와 다를 때의 판정입니다(`JPKI_AND_OCR_DATA_NOT_SAME`). 기본값은 `REVIEW`입니다. |
| `status_rules` | array | 선택 사항인 사용자 지정 상태 규칙입니다. |

## 라이브니스 감지

기능 값: `LIVENESS`.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `face_liveness_method` | string | `ACTIVE_3D`, `FLASHING`, `PASSIVE` 중 하나입니다. |
| `face_liveness_mode` | string | 라이브니스 모드 재정의 값입니다. |
| `face_liveness_flash_mode` | string | `ACTIVE_3D` 및 `FLASHING` 방식의 플래시 모드입니다. `"0"`(엄격하지 않음, 기본값)은 화면에서 깜박인 색상이 사용자 얼굴에 반사되는지 확인합니다. `"1"`(엄격)은 반사가 정확한 플래시 색상 순서와도 일치하는지 추가로 요구합니다. 재생 공격과 비디오 주입 공격에 더 강하지만, 잘못된 거부가 더 많이 발생합니다. |
| `face_liveness_score_decline_threshold` | integer | 거부 임계값입니다. |
| `face_liveness_score_review_threshold` | integer | 검토 임계값입니다. |
| `face_liveness_possible_duplicated_face_action` | action | 얼굴이 중복되었을 수 있을 때의 작업입니다. |
| `face_liveness_multiple_faces_action` | action | 여러 얼굴이 감지되었을 때의 작업입니다. |
| `face_liveness_video_anomaly_action` | action | 저장된 녹화본에 반복되는 움직임 시퀀스가 포함되어 있을 때의 작업입니다. 기본값은 `NO_ACTION`이며, `REVIEW`와 `DECLINE`은 결정된 인증을 비동기적으로 상향 처리할 수 있습니다. 드문드문 있거나 반복되는 정지 프레임만으로는 이 작업이 트리거되지 않습니다. |
| `face_liveness_attack_face_match_action` | action | 라이브니스 얼굴이 같은 애플리케이션의 이전 세션에 있던, 다른 사용자의 얼굴과 일치하고 그 촬영이 높은 신뢰도로 라이브니스 공격으로 판정되었을 때의 작업입니다(경고 `FACE_MATCHES_LIVENESS_ATTACK`). `NO_ACTION` 또는 `REVIEW`를 허용합니다. `DECLINE`도 허용되지만 `REVIEW`로 적용됩니다. 정상 사용자가 실수로 한 번 거부된 뒤 통과할 수 있기 때문입니다. 기본값은 `NO_ACTION`입니다. |
| `race_map_similarity_thresholds` | object | 인구통계 그룹별 유사도 임계값입니다. |
| `face_privacy_mode_enabled` | boolean | 얼굴 자산에 대한 개인정보 보호 모드를 활성화합니다. |
| `face_quality_review_threshold` | integer | 얼굴 이미지 품질의 검토 임계값입니다. |
| `face_quality_decline_threshold` | integer | 얼굴 이미지 품질의 거부 임계값입니다. 검토 임계값보다 작거나 같아야 합니다. |
| `face_luminance_min_threshold` | integer | 최소 밝기 임계값입니다. `face_luminance_max_threshold`보다 작아야 합니다. |
| `face_luminance_min_action` | action | 밝기가 너무 낮을 때의 작업입니다. |
| `face_luminance_max_threshold` | integer | 최대 밝기 임계값입니다. |
| `face_luminance_max_action` | action | 밝기가 너무 높을 때의 작업입니다. |
| `face_liveness_max_attempts` | integer | 세션당 라이브니스 제출 총 횟수이며, `1`부터 `3`까지 설정할 수 있습니다. 기본값 `3`은 최초 시도 1회와 재시도 2회를 의미합니다. `1`로 설정해도 촬영 품질 실패에 대한 재시도는 비활성화되지 않습니다. 시도의 모든 경고가 환경적 요인(`LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, `NO_FACE_DETECTED`)인 경우, 사용자는 항상 실행 가능한 피드백과 함께 두 번째 시도를 받습니다. |
| `cross_org_fraud_face_action` | action | **더 이상 사용되지 않으며 적용되지 않습니다.** 얼굴을 사기 판정이 있는 것처럼 취급했는데, 변하지 않는 생체 신원은 그럴 수 없습니다. 기존 워크플로가 계속 검증을 통과하도록 여전히 허용됩니다. 대신 `cross_org_identity_claim_pattern_action`을 사용하세요. |
| `cross_org_identity_claim_pattern_action` | action | 네트워크의 다른 조직들이 같은 사람에 대해 신원 주장 이벤트를 기록했고, 그 주장된 신원이 일치하지 않았을 때의 판정입니다. 검토 또는 조치 없음만 가능하며, 여기서 설정한 거부는 검토로 하향됩니다. 자세한 내용은 [조직 간 신원 주장](https://docs.didit.me/ko/core-technology/liveness/cross-organization-identity-claims.md)을 참조하세요. |
| `external_capture_device_action` | action | 외부 촬영 장치가 감지되었을 때의 판정입니다. |
| `face_audio_recording_enabled` | boolean | 검토자가 세션을 들을 수 있도록 셀피 촬영 중 마이크의 오디오를 녹음합니다. 기본적으로 꺼져 있습니다. |
| `face_search_enabled` | boolean | 셀피에 대해 자동 [얼굴 검색 1:N](https://docs.didit.me/ko/core-technology/face-search/overview.md#자동-얼굴-검색-끄기)을 실행합니다. 이전에 인증된 사용자, 얼굴 차단 목록과 허용 목록과 대조하고, 나중의 대조를 위해 생체 인식 템플릿을 저장합니다. 기본적으로 켜져 있습니다. `false`로 설정하면 검색을 건너뛰고, 이 단계에서는 얼굴 템플릿을 저장하지 않으며, 중복 얼굴 작업은 처리할 대상이 없습니다. |
| `face_liveness_uncertain_retry_enabled` | boolean | 네이티브 SDK의 능동 라이브니스에만 적용됩니다. 활성화하면 라이브니스 점수가 `face_liveness_score_decline_threshold`와 `face_liveness_score_review_threshold` 사이에 엄격하게 놓인 촬영은, 엔진이 어떤 판정을 붙였든 결정되지 않습니다. 사용자에게 결과가 불분명했다고 알리고 매번 다시 촬영하도록 요청하며, 이 재촬영은 `face_liveness_max_attempts` 한도와 별개로 적용됩니다. 다만 엔진이 점수를 매기지 못한 촬영에는 그 시도 횟수 한도가 여전히 적용됩니다. 기본적으로 꺼져 있으며, 웹 흐름에서는 이 설정을 무시합니다. |
| `face_liveness_duplicated_face_name_mismatch_action` | action | 중복 얼굴이 다른 이름으로 발견되었을 때의 판정입니다. |
| `face_liveness_duplicated_face_document_mismatch_action` | action | 중복 얼굴이 발견되었고 일치한 사용자의 신분증에 다른 생년월일이 표시되어 있을 때의 판정입니다. 다른 문서나 갱신된 문서를 가진 같은 사람은 표시되지 않습니다. 기본값은 `REVIEW`입니다. |
| `frame_injection_action` | action | 주입된 비디오 프레임이 감지되었을 때의 판정입니다. |
| `screen_capture_action` | action | 셀피가 화면을 찍은 사진일 때의 판정입니다. |
| `virtual_camera_action` | action | 가상 카메라 피드가 감지되었을 때의 판정입니다. |
| `status_rules` | array | 선택 사항인 사용자 지정 상태 규칙입니다. |

## 얼굴 대조

기능 값: `FACE_MATCH`.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `face_match_score_decline_threshold` | 정수 | 거부 임계값. |
| `face_match_score_review_threshold` | 정수 | 검토 임계값. |
| `face_match_max_attempts` | 정수 | 세션당 총 얼굴 대조 제출 횟수이며, `1`에서 `3` 사이입니다. 기본값 `3`은 최초 시도 1회와 재시도 2회를 의미합니다. |
| `face_match_not_computed_action` | 제한된 작업 | 얼굴 대조 점수를 산출할 수 없을 때(초상 사진 또는 셀피 누락)의 판정. |
| `face_match_eyes_covered_action` | 작업 | 셀피에서 눈 영역이 가려졌을 때의 판정. 기본값은 `NO_ACTION`이며, 이 경우 얼굴 대조 결과를 바꾸지 않고 증거만 기록합니다. 이 신호는 아직 보정 중이므로, 해당 영역이 보정 완료로 보고되기 전까지는 섀도 전용으로 유지됩니다. 지금 `REVIEW` 또는 `DECLINE`을 설정하면, 해당 영역이 보정 완료로 보고되는 시점부터 적용됩니다. |
| `face_match_mouth_covered_action` | 작업 | 셀피에서 입 영역이 가려졌을 때의 판정. 기본값은 동일하게 `NO_ACTION`이며, 보정 관련 주의 사항도 `face_match_eyes_covered_action`과 같습니다. |
| `face_match_face_covered_action` | 작업 | 셀피에서 얼굴 전체가 가려졌을 때의 판정. 기본값은 동일하게 `NO_ACTION`이며, 보정 관련 주의 사항도 `face_match_eyes_covered_action`과 같습니다. |
| `status_rules` | 배열 | 선택 사항인 사용자 정의 상태 규칙. |

## 연령 추정

기능 값: `AGE_ESTIMATION`.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `enable_id_verification_fallback` | boolean | 연령 추정 결과가 경계 범위에 들어가면 신분증 인증을 실행합니다. |
| `minimum_age_threshold` | integer | 허용되는 최소 연령이며, `1`에서 `100` 사이입니다. |
| `borderline_minimum_age_threshold` | integer | 경계 범위의 하한이며, `1`에서 `100` 사이입니다. |
| `borderline_maximum_age_threshold` | integer | 경계 범위의 상한이며, `1`에서 `100` 사이입니다. |
| `face_liveness_method` | string | `ACTIVE_3D`, `FLASHING`, `PASSIVE` 중 하나입니다. |
| `face_liveness_flash_mode` | string | `ACTIVE_3D` 및 `FLASHING` 방식의 플래시 모드입니다. `"0"`(비엄격, 기본값)은 화면에 점멸된 색상이 사용자 얼굴에 반사되는지 확인합니다. `"1"`(엄격)은 여기에 더해 반사가 점멸된 색상 순서와 정확히 일치하는지도 요구합니다. |
| `face_liveness_score_decline_threshold` | number | 연령 추정에 사용되는 라이브니스 검사의 거부 임계값입니다. |
| `face_liveness_score_review_threshold` | number | 연령 추정에 사용되는 라이브니스 검사의 검토 임계값입니다. |
| `face_liveness_possible_duplicated_face_action` | action | 얼굴이 중복되었을 가능성이 있을 때의 작업입니다. |
| `face_liveness_multiple_faces_action` | action | 여러 얼굴이 감지되었을 때의 작업입니다. |
| `face_liveness_video_anomaly_action` | action | 저장된 녹화본에 반복되는 움직임 시퀀스가 포함된 경우의 작업입니다. 기본값은 `NO_ACTION`입니다. `REVIEW`와 `DECLINE`은 이미 결정된 인증을 비동기로 상향 조정할 수 있습니다. 드문드문하거나 반복되는 정지 프레임만으로는 이 작업이 트리거되지 않습니다. |
| `face_liveness_attack_face_match_action` | action | 라이브니스 얼굴이 같은 애플리케이션의 이전 세션에서 나온 얼굴과 일치하고, 그 얼굴의 다른 사용자 촬영이 높은 신뢰도로 라이브니스 공격으로 판정된 경우의 작업입니다(경고 `FACE_MATCHES_LIVENESS_ATTACK`). `NO_ACTION` 또는 `REVIEW`를 허용합니다. `DECLINE`도 허용되지만 `REVIEW`로 적용됩니다. 정상 사용자가 실수로 한 번 거부된 뒤 통과할 수 있기 때문입니다. 기본값은 `NO_ACTION`입니다. |
| `face_privacy_mode_enabled` | boolean | 얼굴 자산에 대한 개인정보 보호 모드를 활성화합니다. |
| `face_quality_review_threshold` | integer | 얼굴 품질의 검토 임계값입니다. |
| `face_quality_decline_threshold` | integer | 얼굴 품질의 거부 임계값입니다. |
| `face_luminance_min_threshold` | integer | 최소 밝기 임계값입니다. |
| `face_luminance_min_action` | action | 밝기가 너무 낮을 때의 작업입니다. |
| `face_luminance_max_threshold` | integer | 최대 밝기 임계값입니다. |
| `face_luminance_max_action` | action | 밝기가 너무 높을 때의 작업입니다. |
| `face_liveness_max_attempts` | integer | 세션당 라이브니스 제출 총 횟수이며, `1`에서 `3` 사이입니다. 기본값 `3`은 최초 시도 1회와 재시도 2회를 뜻합니다. `1`로 설정해도 촬영 품질 실패에 대한 재시도는 비활성화되지 않습니다. 시도의 모든 경고가 환경적 요인(`LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, `NO_FACE_DETECTED`)이면 사용자는 항상 실행 가능한 안내와 함께 두 번째 시도를 받습니다. |
| `external_capture_device_action` | action | 외부 촬영 장치가 감지되었을 때의 판정입니다. |
| `face_audio_recording_enabled` | boolean | 셀피 촬영 중 마이크를 녹음하여 검토자가 세션을 들을 수 있도록 합니다. 기본적으로 꺼져 있습니다. |
| `face_search_enabled` | boolean | 셀피에 대해 자동 [얼굴 검색 1:N](https://docs.didit.me/ko/core-technology/face-search/overview.md#자동-얼굴-검색-끄기)을 실행합니다. 이전에 인증된 사용자, 얼굴 차단 목록 및 허용 목록과 대조하고, 이후 대조를 위해 생체 인식 템플릿을 저장합니다. 기본적으로 켜져 있습니다. `false`로 설정하면 검색을 건너뛰고, 이 단계의 얼굴 템플릿을 보관하지 않으며, 중복 얼굴 작업이 처리할 대상이 없게 됩니다. |
| `face_liveness_uncertain_retry_enabled` | boolean | 네이티브 SDK 능동형 라이브니스에만 적용됩니다. 활성화하면 라이브니스 점수가 `face_liveness_score_decline_threshold`와 `face_liveness_score_review_threshold` 사이에 엄격하게 놓이는 촬영은 엔진이 어떤 판정을 붙였든 결정되지 않습니다. 사용자에게 결과가 불명확했다고 안내하고 매번 다시 촬영하도록 요청하며, 이는 `face_liveness_max_attempts` 한도 밖에서 이루어집니다(엔진이 점수를 매기지 못한 촬영에는 여전히 이 한도가 적용됩니다). 기본적으로 꺼져 있으며, 웹 흐름에서는 이 설정을 무시합니다. |
| `face_liveness_duplicated_face_name_mismatch_action` | action | 중복 얼굴이 다른 이름으로 발견되었을 때의 판정입니다. |
| `face_liveness_duplicated_face_document_mismatch_action` | action | 중복 얼굴이 발견되었고 일치한 사용자의 신분증에 다른 생년월일이 표시된 경우의 판정입니다. 다른 또는 갱신된 문서를 가진 동일 인물은 표시되지 않습니다. 기본값은 `REVIEW`입니다. |
| `frame_injection_action` | action | 주입된 비디오 프레임이 감지되었을 때의 판정입니다. |
| `screen_capture_action` | action | 셀피가 화면을 촬영한 사진일 때의 판정입니다. |
| `virtual_camera_action` | action | 가상 카메라 피드가 감지되었을 때의 판정입니다. |
| `status_rules` | array | 선택 사항인 사용자 지정 상태 규칙입니다. |

## 전화번호 인증

기능 값: `PHONE_VERIFICATION`.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `code_size` | 정수 | OTP 자릿수이며, `4`에서 `8`까지 설정할 수 있습니다. |
| `phone_max_retries` | 정수 | 최대 전송 재시도 횟수이며, `1`에서 `5`까지 설정할 수 있습니다. |
| `phone_max_check_attempts` | 정수 | 최대 OTP 확인 시도 횟수이며, `1`에서 `5`까지 설정할 수 있습니다. |
| `phone_verification_countries` | 객체 | ISO2 국가 코드와 채널 설정의 매핑입니다. 예시: `{ "US": { "sms": { "enabled": true } } }`. |
| `disposable_number_action` | 작업 | 일회용 번호에 대한 작업입니다. |
| `voip_number_action` | 작업 | VoIP 번호에 대한 작업입니다. |
| `duplicated_phone_number_action` | 작업 | 중복된 전화번호에 대한 작업입니다. |
| `high_risk_phone_action` | 작업 | 전송 제공업체가 OTP 전송을 차단할 때의 작업입니다. `DECLINE` 또는 `REVIEW`만 설정할 수 있으며, 기본값은 `DECLINE`입니다. 단계의 모든 차단 건에 `risk_factors`가 정확히 `["device_attribute"]`로만 포함된 경우에만 적용됩니다. 그 밖의 위험 요소가 있거나, 이 요소가 다른 요소와 섞여 있거나, 위험 요소가 전혀 없으면 이 설정과 관계없이 거부됩니다. |
| `phone_shared_device_mode` | 불리언 | 공유 기기 전화번호 인증 모드를 허용합니다. |
| `phone_enrichment_enabled` | 불리언 | 전화번호 인텔리전스 보강을 활성화합니다(회선 유형 위험, 신뢰 지수, 통신사, 번호 이동 및 SIM 스왑 이력, 사기 위험 점수 포함). **전화번호 인증 요금 외에 인증 건당 \$0.05가 청구됩니다.** |
| `phone_intelligence_score_action` | 작업 | 전화번호 사기 위험 점수가 `phone_intelligence_score_threshold` 이상일 때의 작업입니다. |
| `phone_intelligence_score_threshold` | 정수 | `phone_intelligence_score_action`을 발동시키는 사기 위험 점수입니다(`0`–`100`, 값이 높을수록 위험). 기본값은 `80`입니다. |
| `phone_type_risk_action` | 작업 | 번호가 고위험 전화 유형으로 표시되었을 때의 작업입니다. |
| `recent_port_action` | 작업 | 번호가 최근에 번호 이동된 경우의 작업입니다(SIM 스왑 및 번호 이동 신호). |
| `low_phone_trust_action` | 작업 | 전화번호 신뢰 지수가 `phone_trust_index_threshold` 이하일 때의 작업입니다. |
| `phone_trust_index_threshold` | 정수 | `low_phone_trust_action`을 적용하는 신뢰 지수 기준입니다(`0`–`100`, 값이 낮을수록 위험). 기본값은 `30`입니다. |
| `phone_social_enabled` | 불리언 | 소셜 활동 흔적 확인을 활성화합니다. 인증된 번호가 등록된 메시징, 소셜, 전자상거래 및 전문 플랫폼을 확인합니다. `phone_enrichment_enabled`와 관계없이 적용되며, **전화번호 인증 요금 외에 인증 건당 \$0.05가 청구됩니다.** |
| `phone_no_social_presence_action` | 작업 | 소셜 활동 흔적 확인에서 번호가 확인 대상 플랫폼 어디에도 등록되어 있지 않을 때의 작업입니다. 합성 신원의 흔한 신호입니다. 기본값은 `NO_ACTION`입니다. |
| `cross_org_fraud_phone_action` | 작업 | 네트워크의 다른 조직이 이 번호를 사기로 표시했을 때의 판정입니다. |
| `status_rules` | 배열 | 선택 사항인 사용자 지정 상태 규칙입니다. |

전화번호 인증은 조직이 첫 충전을 완료할 때까지 비활성화되어 있습니다.

> [!NOTE]
>
> 전화번호 인텔리전스 보강은 선택 부가 기능입니다. `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_code_size` | 정수 | OTP 길이이며, `4`부터 `8`까지입니다. |
| `email_max_retries` | 정수 | 최대 전송 재시도 횟수이며, `1`부터 `5`까지입니다. |
| `email_max_check_attempts` | 정수 | 최대 OTP 확인 시도 횟수이며, `1`부터 `5`까지입니다. |
| `email_alphanumeric_code` | 불리언 | 영문자와 숫자를 조합한 이메일 코드를 사용합니다. |
| `breached_email_action` | 작업 | 유출된 이메일에 대한 작업입니다. |
| `disposable_email_action` | 작업 | 일회용 이메일에 대한 작업입니다. |
| `duplicated_email_action` | 작업 | 중복된 이메일에 대한 작업입니다. |
| `only_corporate_emails_allowed` | 불리언 | 기업용이 아닌 이메일 주소를 거부합니다. |
| `email_enrichment_enabled` | 불리언 | 이메일 인텔리전스 보강을 활성화합니다(전송 가능성, 도메인 평판, 데이터 유출 노출, 사기 위험 점수). **인증 건당 \$0.05가 과금되며**, 이메일 인증 요금에 추가됩니다. |
| `email_intelligence_score_action` | 작업 | 이메일 사기 위험 점수가 `email_intelligence_score_threshold` 이상일 때의 작업입니다. |
| `email_intelligence_score_threshold` | 정수 | `email_intelligence_score_action`을 트리거하는 사기 위험 점수(`0`–`100`, 높을수록 위험)입니다. 기본값은 `80`입니다. |
| `recent_email_breach_action` | 작업 | 이메일이 최근 알려진 데이터 유출 사고에 포함된 경우의 작업입니다. |
| `frequent_email_breach_action` | 작업 | 이메일이 여러 알려진 데이터 유출 사고에 반복적으로 포함된 경우의 작업입니다. |
| `email_social_enabled` | 불리언 | 소셜 흔적 확인을 활성화합니다. 인증된 주소가 등록된 이메일, 소셜 미디어, 전문 네트워킹, 전자상거래 및 엔터테인먼트 플랫폼을 확인합니다. **인증 건당 \$0.05가 과금되며**, 이메일 인증 요금에 추가됩니다. `email_enrichment_enabled`와는 무관합니다. |
| `email_no_social_presence_action` | 작업 | 소셜 흔적 확인에서 해당 주소가 확인 대상 플랫폼 중 어디에도 등록되어 있지 않은 것으로 나타날 때의 작업입니다. 합성 신원의 흔한 신호입니다. 기본값은 `NO_ACTION`입니다. |
| `cross_org_fraud_email_action` | 작업 | 네트워크의 다른 조직이 이 주소를 사기로 표시했을 때의 판정입니다. |
| `status_rules` | 배열 | 선택적인 사용자 지정 상태 규칙입니다. |

> [!NOTE]
>
> 이메일 인텔리전스 보강은 선택 추가 기능입니다. `email_enrichment_enabled`가 `true`이면 완료된 각 이메일 인증에 이메일 인텔리전스가 보강되며, 표준 이메일 인증 비용에 더해 **요청당 \$0.05가 청구됩니다**. 점수 기반 작업은 보강 점수를 사용할 수 있게 된 후에 적용되며, 유출 관련 작업은 보강이 실행되는 즉시 적용됩니다.
>
> 소셜 흔적 확인은 별도의 두 번째 선택 추가 기능입니다. `email_social_enabled`가 `true`이면 완료된 각 이메일 인증에서도 해당 주소가 등록된 온라인 플랫폼(이메일 제공업체, 소셜 미디어, 전문 네트워킹, 전자상거래 및 엔터테인먼트 서비스)을 보고하며, **요청당 \$0.05가 청구됩니다**. `email_enrichment_enabled`와 함께 또는 단독으로 활성화할 수 있으며, 두 추가 기능은 가격과 청구가 독립적으로 적용됩니다. 확인 대상 플랫폼 중 어디에도 주소가 등록되어 있지 않다는 조회 결과도 유효하고 과금되는 응답이며, `email_no_social_presence_action`을 트리거합니다. 워크플로 그래프에서 결과에 따라 분기하려면 `email.social_profiles_registered`(주소가 등록된 플랫폼 수)를 사용하십시오.

## Database Validation

기능 값: `DATABASE_VALIDATION`.

| 설정 필드 | 타입 | 설명 |
| - | - | - |
| `database_validation_countries` | object | ISO3 국가 코드를 `{ "services": ["service_id"] }` 형식에 매핑합니다. 데이터베이스 검증 카탈로그의 서비스 ID를 사용하세요. |
| `database_validation_partial_match_action` | action | 데이터베이스 검증이 부분 일치를 반환할 때의 작업입니다. |
| `database_validation_no_match_action` | action | 데이터베이스 검증이 일치하는 결과를 반환하지 않을 때의 작업입니다. |
| `database_validation_not_applicable_action` | action | 문서에 구성된 서비스에 필요한 식별자가 없어 데이터베이스 검증을 실행할 수 없을 때의 작업입니다(예: 국민 ID 번호가 없는 여권). 기본값은 `NO_ACTION`입니다. |
| `database_validation_field_sources` | object | 그래프의 이전 단계에서 채울 수 없는 데이터베이스 입력값을 어디에서 읽을지 지정합니다. `source`는 생성 주체를, `key`는 그 안의 값을 나타냅니다. `document_ai`의 경우 Document AI 필드 키, `questionnaire`의 경우 설문지 노드 ID, `expected_data`의 경우 `expected_details.<field>` 또는 `metadata.<key>`를 사용합니다. 상위 단계와 키가 정확히 일치하는 항목은 자동으로 해석되며 의도적으로 저장되지 않습니다. 따라서 Document AI 필드 이름을 바꿔도 오래된 매핑이 설정에 고정되지 않습니다. 잘못된 항목은 입력 필드 이름을 포함한 `400` 오류로 거부됩니다. 형식: `{"<db_validation_input_field>": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<field>\|metadata.<key>"}}` |
| `status_rules` | array | 선택 사항인 사용자 지정 상태 규칙입니다. |

예시:

```json theme={null}
{
  "feature": "DATABASE_VALIDATION",
  "config": {
    "database_validation_countries": {
      "BRA": {
        "services": ["SERVICE_ID_FROM_CATALOG"]
      }
    },
    "database_validation_field_sources": {
      "tax_id": {
        "source": "expected_data",
        "key": "expected_details.document_number"
      }
    },
    "database_validation_no_match_action": "REVIEW",
    "database_validation_partial_match_action": "REVIEW"
  }
}
```

> [!WARNING]
>
> `database_validation_countries`가 있어야 이 단계가 동작합니다. 이 값 없이 저장된 `DATABASE_VALIDATION` 기능은 허용되지만 어떤 검사도 실행하지 않습니다. 따라서 국가 하나와 서비스 ID 하나 이상을 반드시 함께 전송하세요.

실행할 수 없는 서비스 ID는 `400` 오류로 거부되며, 오류 메시지에 해당 ID와 거부 이유가 포함됩니다. 이 경우 아무것도 저장되지 않습니다. 거부 대상은 카탈로그에 없는 ID, 다른 국가에 속한 ID, 아직 제공되지 않는 서비스, 그리고 단독 [`POST /v3/database-validation/`](https://docs.didit.me/ko/core-technology/database-validation/overview) 엔드포인트를 통해서만 제공되는 서비스입니다. 입력값을 이전 단계에서 제공하지 않는 서비스도 같은 방식으로 거부되며, 누락된 입력값 목록이 함께 표시됩니다. 저장된 워크플로에 이미 포함되어 있지만 더 이상 실행할 수 없는 서비스는 다시 저장할 때 제거됩니다.

예를 들어 다음 아르헨티나 워크플로는 신분증 인증에서 DNI 번호와 성별을 읽고, 셀피 없이 RENAPER의 데이터와 두 값을 대조합니다.

```json theme={null}
{
  "workflow_label": "Argentina DNI check",
  "features": [
    {"feature": "OCR"},
    {
      "feature": "DATABASE_VALIDATION",
      "config": {"database_validation_countries": {"ARG": {"services": ["arg_renaper_data"]}}}
    }
  ]
}
```

셀피도 RENAPER가 보유한 사진과 대조하려면 `LIVENESS` 단계 뒤에 `arg_renaper`를 사용하세요. 얼굴 대조 점수와 임계값은 [RENAPER](https://docs.didit.me/ko/api-reference/database-validation/argentina/renaper.md)를 참고하세요.

## 은행 인증

기능 값: `BANK_VERIFICATION`.

사용자가 은행 계좌를 인증하면, 은행이 확인해 주는 계좌 명의인은 워크플로의 앞선 단계에서 확정된 신원과 비교됩니다. 사용자는 두 가지 방법 중 하나로 인증합니다. 은행 로그인(`open_banking`)은 사용자가 자신의 은행에 로그인하는 방식이고, 계좌 조회(`account_lookup`)는 사용자가 계좌 정보를 입력하면 은행이 해당 계좌의 명의를 확인해 주는 방식입니다. `bank_method_order`와 각 국가의 `methods`는 국가별로 어떤 방식을 제공할지, 그리고 어떤 방식을 먼저 보여 줄지 결정합니다. 자세한 내용은 [은행 인증 방식](https://docs.didit.me/ko/core-technology/bank-verification/verification-methods.md)을 참조하십시오. 이 단계는 명의자 이름 일치 점수, 그 점수를 산출한 비교 내용, 사유 코드 같은 증거를 생성하며, `bank_*_action` 키들이 이 증거를 상태로 변환합니다.

노드가 아무 작업도 수행할지는 두 가지로 결정됩니다. `bank_countries`는 허용 목록이므로 빈 맵이면 은행을 제공하지 않고 확인도 실행하지 않습니다. 또한 사용자의 명의와 비교할 대상이 있어야 합니다. 이 노드 앞에 `OCR`, `DATABASE_VALIDATION` 또는 `QUESTIONNAIRE` 단계를 두거나, 세션 생성 시 `expected_details`를 보내거나, `bank_field_sources`로 필드를 직접 매핑하십시오. 이 중 어느 것도 없으면 소유 여부는 `unknown`으로만 나올 수 있으며, 이 경우의 처리는 `bank_reference_identity_missing_action`이 결정합니다.

> [!NOTE]
>
> 은행 인증은 아직 출시 단계이므로 `BANK_VERIFICATION` 노드는 해당 기능이 활성화된 계정에서만 허용됩니다. 그 밖의 계정에서는 저장이 거부되며, 거부되었다는 사실이 메시지로 표시됩니다. 이 단계를 실행하는 경로 역시 여기서 설정하지 않습니다. 이는 콘솔의 [Marketplace](https://docs.didit.me/ko/console/marketplace.md)에서 설정되는 `provider_key`와 `fallback_to_native` 쌍이 자동으로 정합니다.

### 계좌 연결

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `bank_countries` | object | 사용자가 은행을 연결할 수 있는 국가를 지정합니다. 허용 목록이므로 빈 맵은 노드가 아무것도 제공하지 않고 아무것도 실행하지 않는다는 뜻입니다. `institutions`는 선택 창을 특정 기관 ID로 좁히며, `"all"`은 해당 국가에서 신원 확인이 가능한 모든 은행을 제공합니다. 노드의 어떤 경로도 제공하지 않는 국가는 그대로 유지되며, 이 경우 대체 수단만 제공하고 은행 없이 계속하는 옵션을 제공합니다. 자세한 내용은 [사용자가 은행을 인증할 수 없는 경우](https://docs.didit.me/ko/core-technology/bank-verification/fallbacks.md)를 참조하십시오. 국가를 나타내지 않는 코드는 저장 시 거부됩니다. `methods`는 은행 로그인(`open_banking`)과 계좌 조회(`account_lookup`) 중 해당 국가가 제공할 방식을 순서대로 지정하며, `bank_method_order`보다 우선합니다. 사용자는 첫 번째 방식으로 시작하고, 두 번째 방식이 백업으로 제공됩니다. 활성화된 국가의 `methods`가 노드의 어떤 경로도 제공하지 않는 방식을 지정하면 저장이 거부되며, 경로가 제공하는 방식이 `methods`에서 하나도 남지 않는 국가도 마찬가지로 거부됩니다. 형식: `{"<ISO3>": {"enabled": true\|false, "institutions": ["<institution_id>", ...]\|"all", "methods"?: ["open_banking"\|"account_lookup", ...]}}` |
| `bank_method_order` | string\[] | `methods`를 따로 지정하지 않은 모든 국가에서 이 단계가 제공할 두 방식과 그 순서를 지정합니다. `open_banking`(은행 로그인: 사용자가 자신의 은행에 로그인하며, 잔액, 거래 내역, 소득을 읽는 것은 이 방식뿐입니다)과 `account_lookup`(계좌 조회: 로그인 없이 소유 여부만 확인합니다)이 있습니다. 각 국가에서 사용자는 그 국가에 경로가 제공하는 첫 번째 방식으로 시작하고, 나머지 방식이 백업으로 제공됩니다. 어떤 경로도 제공하지 않는 방식은 해당 국가에서 제외됩니다. 최소 한 개는 있어야 합니다. 값을 보내지 않은 저장에는 `["open_banking", "account_lookup"]`이 적용됩니다. 단, `bank_open_banking_enabled` 또는 `bank_account_lookup_enabled`를 보낸 경우에는 그 값이 이를 설정합니다. |
| `bank_scopes` | object | 사용자가 공유에 동의해야 하는 항목을 지정합니다. `ownership`은 이 제품이 검증하는 항목이며 끌 수 없습니다. `identifiers`는 IBAN 또는 계좌번호의 마스킹을 해제합니다. `balances`, `transactions`, `income`은 실제 금융 데이터를 읽으며, 각각 별도로 과금되고, 애플리케이션에 금융 데이터 권한이 없으면 저장이 거부됩니다. 데이터를 읽는 것은 은행 로그인뿐입니다. 계좌 조회를 제공하는 국가가 있어도 저장이 거부되지 않으며, 계좌 조회로 인증한 사용자는 데이터 없이 통과하고, 그 사실은 결과의 `financial_data.not_collected`에 나열됩니다. 꺼진 범위는 요청되지 않으므로 은행의 동의 화면에 표시되지 않습니다. 기본값은 `ownership`만입니다. 형식: `{"ownership": true, "identifiers": true\|false, "balances": true\|false, "transactions": true\|false, "income": true\|false}` |
| `bank_eligible_account_types` | string\[] | 사용자가 고를 수 있는 계좌 유형을 지정합니다: `checking`, `current`, `savings`, `business`, `other`. 신용카드, 대출, 투자 계좌는 결제 계좌의 소유를 입증하지 않으므로 절대 허용되지 않습니다. 기본값은 current와 checking입니다. |
| `bank_account_selection` | string | `user`는 사용자가 연결된 계좌 중 인증할 계좌를 선택하게 하며, `auto`는 첫 번째 적격 계좌를 자동으로 선택합니다. |
| `bank_require_oauth_only` | boolean | OAuth 또는 앱 간 방식으로 접근할 수 있는 기관만 제공하며, 레거시 자격 증명 입력 화면은 절대 제공하지 않습니다. 오픈 뱅킹에서 이미 OAuth만 사용할 수 있는 시장에서는 아무것도 바뀌지 않습니다. |
| `bank_max_attempts` | integer | 사용자가 은행 로그인을 시도할 수 있는 횟수로 `1`부터 `5`까지입니다. 소액 입금 인증이나 명세서 업로드도 한 번을 사용합니다. 계좌 조회에는 별도의 `bank_account_check_max_attempts`가 있습니다. 명세서 업로드를 포함해 사용자를 인증할 수 있는 모든 방법이 여전히 제공되고 있는데도 성공한 연결 없이 시도 횟수를 모두 소진하면 `bank_attempts_exhausted_action`이 처리 방식을 결정합니다. |
| `bank_connection_timeout_minutes` | integer | 시작된 연결이 열려 있는 시간으로, 이 시간이 지나면 시도가 중단됩니다. `5`부터 `60`분까지 설정할 수 있습니다. |
| `bank_allow_skip` | boolean | `bank_continue_without_bank`로 대체되어 폐기되었습니다. 이제 사용자는 언제든 은행 없이 계속할 수 있습니다. 한 릴리스 동안은 `bank_continue_without_bank`를 보내지 않은 저장에서 이 값을 읽습니다. `true`이면 `from_start`, 그 밖의 값이면 `when_needed`로 설정됩니다. 모든 저장은 이 값을 다시 기록합니다. `from_start`이면 `true`, `when_needed`이면 `false`입니다. |

### 사용자가 인증할 수 없는 경우

사용자는 언제든 은행 없이 계속할 수 있으며, 이 단계가 사용자를 막다른 길에 두는 일은 없습니다. 자세한 내용은 [사용자가 은행을 인증할 수 없는 경우](https://docs.didit.me/ko/core-technology/bank-verification/fallbacks.md)를 참조하십시오.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `bank_continue_without_bank` | string | **Continue without your bank** 단계를 표시하는 시점을 정합니다. 기본값인 `when_needed`는 사용자의 국가나 은행을 지원하는 방법이 없을 때, 은행에 연결할 수 없고 다른 방법으로도 확인할 수 없을 때(예: 계좌 확인도 은행에 연결하지 못한 경우), 또는 온라인 뱅킹이 없다고 답했을 때 이 단계를 한 번 표시합니다. `from_start`는 첫 화면에서도 이 단계를 표시합니다. 이 설정은 끌 수 없습니다. 이 키와 `bank_allow_skip`을 모두 보내지 않고 저장하면 `when_needed`가 적용됩니다. |
| `bank_statement_standalone_enabled` | boolean | `bank_statement_enabled`와 함께 사용하면, 은행 시도가 전혀 없었더라도 모든 국가에서 명세서 업로드를 제공합니다. 은행 로그인이나 계좌 확인 경로가 지원하지 않는 국가도 포함됩니다. 이 경우 명세서는 `bank_statement_upload`로 별도 과금되며, 평가된 명세서 1건당 계약 요금 또는 특별 가격을 적용하기 전 기준 요금은 USD 0.20입니다. 요금은 [요금](https://docs.didit.me/ko/core-technology/bank-verification/fallbacks.md#요금)을 참조하십시오. 샌드박스 세션에서는 과금 없이 테스트할 수 있습니다. 기본값은 켜짐입니다. |

사용자가 계속 진행한 이유에 따라, 세션에서 계속 진행을 의미하는 값은 `bank_unsupported_action`, `bank_attempts_exhausted_action` 또는 `bank_skipped_action`입니다. 단, 그보다 먼저 평가된 시도가 이미 단계를 결정한 경우에는 그 결정이 우선합니다. 자세한 내용은 [판정 작업](#판정-작업)을 참조하십시오.

### 명의자 비교

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `bank_reference_identity` | string | 명의자의 신원을 비교할 대상이 되는 이전 단계를 지정합니다. 값은 `kyc`(신분증 인증), `database_validation`, `expected_details`(세션 생성 시 보낸 값), `questionnaire`, 또는 워크플로가 생성한 값을 사용하는 `auto` 중 하나입니다. 실제로 신원 정보를 제공한 단계는 결과의 `reference_identity_source`에 표시됩니다. |
| `bank_field_sources` | object | 그래프의 이전 단계 중 어느 것도 참조 신원 필드를 채울 수 없을 때 해당 필드를 읽을 위치를 지정합니다. 맵의 키는 `full_name`, `first_name`, `last_name`, `address` 중 하나입니다. `source`는 값을 생성하는 출처를, `key`는 그 출처 안에서 값을 가리키는 이름을 지정합니다. `document_ai`에서는 Document AI 필드 키, `questionnaire`에서는 설문지 노드 ID, `expected_data`에서는 `expected_details.<field>` 또는 `metadata.<key>`를 사용합니다. `expected_details.`로 시작하는 값은 세션 생성 페이로드에 실제로 포함된 필드만 지정할 수 있습니다: `address`, `country`, `date_of_birth`, `first_name`, `gender`, `id_country`, `identification_number`, `ip_address`, `last_name`, `nationality`, `poa_country`. 잘못된 항목은 조용히 버려지지 않고 저장 시 거부됩니다. 형식: `{"full_name"\|"first_name"\|"last_name"\|"address": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<field>\|metadata.<key>"}}` |
| `bank_name_match_threshold` | integer | 이 점수 이상이면 명의자 이름이 일치로 판단됩니다. `50`에서 `100` 사이이며 기본값은 `85`입니다. |
| `bank_partial_match_floor` | integer | 이 점수 미만이면 명의자 이름이 불일치로 판단됩니다. `0`에서 `99` 사이이며 기본값은 `70`입니다. 하한과 임계값 사이 구간은 부분 일치이므로, 하한은 반드시 임계값보다 엄격하게 낮아야 합니다. 그렇지 않으면 저장이 거부됩니다. 여기서 명시적인 `null`은 "기본값 사용"을 뜻합니다. 따라서 하한을 지정하지 않고 임계값을 `50`으로 설정하면, 기본 하한 `70`과 비교하여 `50`으로 검사되므로 저장이 거부됩니다. |
| `bank_require_address_match` | boolean | 명의자의 주소도 일치해야 함을 요구합니다. 이름은 임계값에 도달했지만 주소 점수가 임계값보다 낮으면 부분 일치로 낮아집니다. 은행이 주소를 반환하지 않으면 이 요구 사항은 면제됩니다. 반면 세션에 비교할 주소가 없으면 면제되지 않고 부분 일치로 처리됩니다. 기본값은 꺼짐입니다. |
| `bank_use_provider_score` | boolean | 금융기관 자체의 명의자 이름 점수도 읽습니다. 이 점수가 Didit의 점수보다 높거나, Didit이 점수를 매길 명의자 이름이 없는 경우 제공자 점수가 결정을 내립니다. 이렇게 결정된 결과는 일치 방법으로 `provider_only`를 보고합니다. 제공자 점수를 반환하지 않은 연결에서는 `provider_score_unavailable` 경고가 기록됩니다. 기본값은 켜짐입니다. |
| `bank_show_match_result_to_user` | boolean | 인증 흐름 안에서 사용자에게 소유 구조 결과를 표시합니다. 꺼두면 결과는 세션에 기록되지만 사용자에게는 절대 표시되지 않습니다. |

### 계좌 확인

이 키들은 계좌 확인에만 적용됩니다. 은행 로그인은 자체 근접 일치 처리와 `bank_max_attempts`를 그대로 유지합니다.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `bank_account_check_accept_close_match` | boolean | 켜짐(기본값)이면 은행이 `bank_partial_match_floor`와 `bank_name_match_threshold` 사이의 점수를 매긴 이름을 근접 일치로 처리합니다. `bank_suggest_holder_name`이 켜져 있으면 사용자가 은행이 보유한 이름을 확인하고, `bank_partial_match_action`이 결과를 결정합니다. 꺼져 있으면 이 근접 일치는 불일치(`OWNER_NAME_MISMATCH`)가 되며, `bank_no_match_action`에 따라 결정되고 시도 한 번을 소모합니다. |
| `bank_account_check_max_attempts` | integer | 사용자가 계좌 확인을 수행할 수 있는 횟수입니다. `1`에서 `5` 사이이며, 설정하지 않으면 `3`입니다. 은행이 응답하는 확인에 대해 사용자가 계좌 정보를 입력할 수 있는 횟수를 뜻합니다. `bank_max_attempts`와는 별도로 집계됩니다. 입력 형식이 잘못되어 거부된 확인(예: 잘못된 IBAN)이나 은행이 응답하지 못한 확인은 횟수를 소모하지 않습니다. |

### 재무 데이터

`bank_expected_currencies`는 기본값인 `ownership` 동의만으로 동작합니다. 나머지 세 키는 실제 재무 데이터를 읽으므로 각각 `bank_scopes`에 해당 동의 범위가 있어야 하며, 없으면 저장이 거부됩니다.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `bank_expected_currencies` | string\[] | 계좌가 사용할 것으로 예상되는 ISO 4217 통화입니다. 비워 두면 모든 통화를 허용합니다. 통화가 일치하지 않으면 `bank_currency_mismatch_action`을 통해 보고됩니다. |
| `bank_min_balance` | number | 계좌 자체 통화 기준의 최소 사용 가능 잔액입니다. 잔액이 이 값보다 낮으면 `bank_low_balance_action`이 실행됩니다. `balances` 범위가 필요합니다. `0`은 실제 기준값이며, 키를 생략한 것과 다릅니다. 잔액이 마이너스인 계좌도 작업을 트리거합니다. 이 작업의 기본값은 `NO_ACTION`으로, 판정 결과를 바꾸지 않습니다. 따라서 잔액이 마이너스인 계좌를 거부하려면 `bank_low_balance_action: "DECLINE"`도 함께 설정해야 합니다. |
| `bank_transactions_history_days` | integer | 거래 내역을 읽어 오는 기간입니다. `30`일에서 `365`일 사이이며 기본값은 `90`입니다. `transactions` 범위가 필요합니다. |
| `bank_refresh_enabled` | boolean | 단계의 판정이 이미 내려진 후에도 은행 동의가 유효한 동안 계좌의 금융 데이터를 다시 가져옵니다. `balances`, `transactions`, `income` 범위 중 하나 이상이 필요합니다. 이후 동의가 만료되는 경우의 판정은 `bank_consent_expired_action`으로 설정합니다. |

### 저장되는 항목

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `bank_store_full_identifiers` | boolean | 계좌 식별자를 마스킹하지 않은 상태로 저장합니다. 마스킹된 형태로 저장하지 않습니다. `identifiers` 범위가 필요합니다. 그래도 마스킹되지 않은 형태는 은행 인증 읽기 권한을 가진 호출자에게만 반환됩니다. |
| `bank_store_raw_owner_data` | boolean | 기관이 반환한 명의자 정보를 소유권 증거와 함께 보관합니다. 끄면 점수, 일치 방식, 사유 코드 등 비교 결과만 보관됩니다. |

### 판정 작업

설정 항목은 제한됨으로 표시되지 않는 한 모두 `DECLINE`, `REVIEW`, `NO_ACTION` 중 하나를 받으며, 생략하거나 `null`을 보내면 아래의 기본값이 적용됩니다. 적극적인 소유권 증거가 아닌 것은 기본적으로 승인되지 않으며, 사용자에게 불리한 명확한 증거가 있을 때에만 거부됩니다.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `bank_no_match_action` | 제한된 작업 | 계좌 명의자가 인증된 사람이 아님이 명백한 경우의 판정입니다. 최고 이름 점수가 `bank_partial_match_floor`보다 낮을 때 적용됩니다. `DECLINE` 또는 `REVIEW`를 사용하세요. 기본값은 `DECLINE`입니다. |
| `bank_partial_match_action` | 작업 | 명의자 이름이 `bank_partial_match_floor`와 `bank_name_match_threshold` 사이에 있을 때의 판정입니다. 기본값은 `REVIEW`이며, 기본적으로 승인하지 않습니다. |
| `bank_not_verifiable_action` | 작업 | 기관은 연결되었지만 비교할 명의자 정보를 반환하지 않은 경우의 판정입니다. 기본값은 `REVIEW`입니다. |
| `bank_unknown_action` | 작업 | 재시도 후에도 증거를 가져오지 못한 경우, 즉 일시적인 실패일 때의 판정입니다. 기본값은 `REVIEW`입니다. |
| `bank_reference_identity_missing_action` | 작업 | 이전 단계에서 명의자와 비교할 신원이 만들어지지 않아 소유 여부를 `unknown`으로만 판단할 수 있을 때의 판정입니다. 기본값은 `REVIEW`입니다. |
| `bank_joint_account_action` | 작업 | 계좌의 명의자가 둘 이상일 때의 판정입니다. 기본값은 `NO_ACTION`입니다. |
| `bank_business_account_action` | 작업 | 기관이 명의자를 개인이 아닌 기업으로 분류한 경우의 판정입니다. 개인 워크플로에서는 기본값이 `REVIEW`이고, 세션이 기업 명의자를 기대하는 기업(KYB) 워크플로에서는 기본값이 `NO_ACTION`입니다. |
| `bank_unsupported_action` | 작업 | 사용자의 국가나 은행을 확인할 방법이 없어 은행 없이 계속 진행한 경우의 판정입니다. 해당 국가를 지원하는 은행 로그인이나 계좌 확인 경로가 없거나, 선택한 은행을 이 단계에서 사용할 수 없는 경우입니다. 이때 결과에는 `continued_without_bank`가 true로 설정되고, 사유 코드에 `NOT_COVERED`가 포함됩니다. 기본값은 `REVIEW`입니다. |
| `bank_skipped_action` | 제한된 작업 | 확인 방법이 있었는데도 사용자가 은행 없이 계속하기를 선택한 경우의 판정입니다. 이때 결과에는 `continued_without_bank`가 true로 설정되고, 사유 코드에 `SKIPPED`가 포함됩니다. `DECLINE` 또는 `REVIEW`를 사용하세요. 기본값은 `REVIEW`입니다. |
| `bank_attempts_exhausted_action` | 제한된 작업 | 사용자가 여전히 제공되는 모든 확인 방법의 시도 횟수를 소진했는데도(명세서 업로드 포함, `bank_max_attempts`, 그리고 해당 국가가 계좌 확인을 제공하는 경우 `bank_account_check_max_attempts`) 은행 연결에 성공하지 못한 경우의 판정입니다. 이후 은행 없이 계속 진행하는 경우에도 적용됩니다. `DECLINE` 또는 `REVIEW`를 사용하세요. 기본값은 `DECLINE`입니다. |
| `bank_consent_expired_action` | 작업 | 단계의 판정이 이미 내려진 후 은행 동의가 만료된 경우의 판정입니다. `bank_refresh_enabled`가 설정된 경우에만 의미가 있습니다. 기본값은 `NO_ACTION`입니다. |
| `bank_currency_mismatch_action` | 작업 | 계좌 통화가 `bank_expected_currencies`에 없는 경우의 판정입니다. 기본값은 `NO_ACTION`입니다. |
| `bank_country_mismatch_action` | 작업 | 기관의 국가가 예상 국가나 문서 국가와 다른 경우의 판정입니다. 기본값은 `NO_ACTION`입니다. |
| `bank_low_balance_action` | 작업 | 사용 가능한 잔액이 `bank_min_balance`보다 낮은 경우의 판정입니다. `balances` 범위가 필요합니다. 기본값은 `NO_ACTION`입니다. |
| `status_rules` | array | 선택 사항인 사용자 지정 상태 규칙입니다. |

### 추가 설정

이 설정 항목들은 선택 사항입니다. 각 작업 항목은 `DECLINE`, `REVIEW`, `NO_ACTION` 중 하나를 받습니다.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `bank_abandoned_action` | 작업 | 사용자가 은행에서 이탈한 뒤 돌아오지 않아 단계가 일치 없이 끝난 경우(시도 시간 초과)의 판정입니다. |
| `bank_account_age_action` | 작업 | 계좌 개설 후 경과 기간이 `bank_account_age_days`보다 짧은 경우의 판정입니다. 흔히 보이는 머니 뮬 패턴입니다. |
| `bank_account_age_days` | integer | 거래 내역의 시작일이 이 일수보다 최근인 계좌는 새 계좌로 간주합니다. 1일에서 365일 사이이며 기본값은 30입니다. 거래 내역에서 읽으므로 `transactions` 범위가 있을 때만 사용됩니다. |
| `bank_account_lookup_enabled` | boolean | 지원이 중단되었습니다. `bank_method_order`와 `bank_countries.<ISO3>.methods`를 사용하세요. 한 릴리스 동안은 `bank_method_order`를 보내지 않은 저장 요청에서 읽힙니다. `bank_open_banking_enabled`와 함께 사용하면 순서를 설정하며, 은행 로그인 후 계좌 확인이 켜져 있으면 포함되고, 꺼져 있거나 설정되지 않으면 제외됩니다. 저장할 때마다 어느 국가든 계좌 확인을 제공하는지 여부로 다시 기록됩니다. |
| `bank_account_type_action` | 작업 | 확인된 계좌가 저축 계좌인 경우의 판정입니다. |
| `bank_address_match_threshold` | integer | 이 점수 이상이면 명의자의 주소가 일치하는 것으로 봅니다. 50에서 100 사이이며 기본값은 70입니다. `bank_require_address_match`가 설정된 경우에만 읽힙니다. |
| `bank_address_mismatch_action` | 작업 | 명의자의 주소가 다른 경우의 판정입니다. 이때 일치는 근접 일치로 바뀝니다. `bank_require_address_match`가 설정된 경우에만 적용됩니다. |
| `bank_auto_add_countries` | boolean | 노드를 저장한 뒤 추가된 국가를 포함하여, 이 노드가 제공할 수 있는 모든 국가에 경로를 제공합니다. 다만 `bank_countries`에서 끈 국가는 제외합니다. 키가 없으면 꺼진 상태이므로, 기존 노드가 스스로 범위를 넓히지 않습니다. |
| `bank_cash_flow_action` | 작업 | 자금이 들어온 뒤 곧바로 빠져나가거나 작은 금액의 이체가 여러 번 들어오는 경우(통과형 현금 흐름)의 판정입니다. `transactions` 범위가 필요합니다. |
| `bank_dob_match_enabled` | boolean | 은행이 생년월일을 제공하는 경우 계좌 명의자의 생년월일을 확인된 생년월일과 비교합니다. 불일치해도 소유 확인 결과는 바뀌지 않으며, `bank_dob_mismatch_action`이 실행됩니다. 기본값은 켜짐입니다. |
| `bank_dob_match_threshold` | integer | 이 점수 이상이면 생년월일이 일치하는 것으로 봅니다. 50\~100 범위이며 기본값은 70입니다. 날짜는 같은 날이거나 다르거나 둘 중 하나이므로 100점 또는 0점을 받습니다. |
| `bank_dob_mismatch_action` | 작업 | 계좌 명의자의 생년월일이 다를 때의 판정입니다. `bank_dob_match_enabled`가 켜져 있을 때만 적용됩니다. |
| `bank_email_match_enabled` | boolean | 은행에 등록된 이메일을 세션에서 확인된 이메일과 비교합니다. 불일치하면 `bank_email_mismatch_action`이 실행됩니다. 기본값은 꺼짐입니다. |
| `bank_email_match_threshold` | integer | 이 점수 이상이면 이메일이 일치하는 것으로 봅니다. 50\~100 범위이며 기본값은 70입니다. |
| `bank_email_mismatch_action` | 작업 | 계좌 명의자의 이메일이 다를 때의 판정입니다. `bank_email_match_enabled`가 켜져 있을 때만 적용됩니다. |
| `bank_evidence_retention_days` | integer | 판정 후 이 일수가 지나면 은행 증빙 자료를 삭제합니다: 30, 90, 365 또는 1825일. null이면 세션과 함께 보관됩니다. 삭제되는 항목은 명의자 정보, 비교 대상이었던 신원 정보, 계좌 식별자, 재무 데이터, 업로드된 명세서입니다. 아직 유효한 연결은 해지됩니다. 판정, 점수, 사유 코드는 남습니다. 세션을 삭제하면 보존 기간과 관계없이 둘 중 먼저 발생하는 시점에 모든 항목이 삭제됩니다. |
| `bank_fallback_used_action` | 작업 | 계좌가 소액 입금 또는 명세서 업로드로 인증되었을 때의 판정입니다. |
| `bank_match_any_holder` | boolean | 공동 또는 공유 계좌는 나열된 명의자 중 한 명이라도 본인과 일치하면 일치하는 것으로 봅니다. 꺼짐이면 은행이 가장 먼저 나열한 명의자만 일치할 수 있습니다. 기본값은 켜짐입니다. |
| `bank_microdeposits_enabled` | boolean | 소액 입금을 대체 수단으로 제공합니다. 계좌로 소액 입금 두 건이 전송되며 사용자는 그 금액을 입력합니다. 이 방식을 보낼 수 있는 경로가 있는 국가에서만 제공되며, 같은 세션에서 과금되는 은행 인증을 시도한 후에 제공됩니다. 추가 요금 없이 포함되며, 고객은 경로 가격을 한 번만 지불합니다. 샌드박스 세션에서는 과금 없이 테스트할 수 있습니다. 명의자는 세션에서 확인된 이름이며, 사용자가 계좌가 그 이름으로 되어 있다고 선언한 이름입니다. 따라서 인증된 계좌에는 `holder_declared` 경고가 기록됩니다. 기본값은 켜짐입니다. |
| `bank_mule_score_action` | 작업 | 머니 뮬 점수가 `bank_mule_score_threshold` 이상일 때의 판정입니다. |
| `bank_mule_score_threshold` | integer | 머니 뮬 점수가 이 값(0\~100) 이상이면 `bank_mule_score_action`이 실행됩니다. 기본값은 70입니다. 이 점수는 신규 계좌, 통과형 현금 흐름, 잔액 소진, 작은 금액의 다수 입금을 조합하며, 거래 내역(`transactions` 범위)에서 읽습니다. |
| `bank_open_banking_enabled` | boolean | 지원 중단되었습니다. `bank_method_order`와 `bank_countries.<ISO3>.methods`를 사용하십시오. `bank_method_order`를 보내지 않는 저장 요청에서는 한 릴리스 동안 이 값을 읽습니다. `bank_account_lookup_enabled`가 켜져 있으면 이 값으로 순서를 설정하고, 이 값이 켜져 있거나 설정되지 않은 경우 은행 로그인도 설정합니다. 저장할 때마다 어떤 국가든 은행 로그인을 제공하는지 여부로 이 값이 다시 기록됩니다. |
| `bank_phone_match_enabled` | boolean | 은행에 등록된 전화번호를 세션에서 확인된 전화번호와 비교합니다. 불일치하면 `bank_phone_mismatch_action`이 실행됩니다. 기본값은 꺼짐입니다. |
| `bank_phone_match_threshold` | integer | 이 점수 이상이면 전화번호가 일치하는 것으로 봅니다. 50\~100 범위이며 기본값은 70입니다. |
| `bank_phone_mismatch_action` | 작업 | 계좌 명의자의 전화번호가 다를 때의 판정입니다. `bank_phone_match_enabled`가 켜져 있을 때만 적용됩니다. |
| `bank_popular_mode` | string | `auto`(기본값)는 국가별로 사람들이 가장 많이 연결하는 순서대로 인기 은행을 정렬합니다. `manual`은 대신 `bank_countries`의 각 국가 `popular_institutions`를 그 순서대로 표시합니다. |
| `bank_statement_document_checks_action` | 작업 | 업로드된 명세서에 편집 또는 변조 흔적이 있을 때의 판정입니다. 기본값은 `REVIEW`입니다. |
| `bank_statement_enabled` | boolean | 명세서 업로드를 대체 수단으로 제공합니다. 최근 3개월 명세서를 받아 변조 여부를 확인하고, 명의자 이름은 은행과 같은 방식으로 대조합니다. 같은 세션에서 과금되는 은행 인증을 시도한 후에는 추가 요금 없이 포함됩니다. `bank_statement_standalone_enabled`를 켜면 앞선 은행 인증 시도 없이 어느 국가에서나 제공되며, 이 경우 별도로 과금됩니다. 샌드박스 세션에서는 과금 없이 테스트할 수 있습니다. 기본값은 꺼짐입니다. |
| `bank_suggest_holder_name` | boolean | 근접 일치 시 은행이 계좌에 등록한 이름을 사용자에게 보여주고, 본인의 계좌인지 확인하거나 다른 계좌를 연결하도록 요청합니다. 응답은 `holder_confirmation`으로 기록되며, 확인하면 단계가 `bank_partial_match_action`에 따라 종료됩니다. 기본값은 켜짐입니다. |
| `fallback_to_native` | boolean | 마켓플레이스 연결을 설정할 수 없을 때 Didit 기본 경로로 대체할지 여부입니다. 기본값은 꺼짐입니다. 조용한 대체는 본인의 제공업체 계약으로 실행될 것으로 예상한 세션에 Didit 잔액을 사용하게 되기 때문입니다. 대체된 연결은 `credential_source = native`로 기록되며 기본 경로 가격으로 과금됩니다. |
| `provider_key` | string | 단계를 실행할 경로입니다. 비워 두면(기본값) Didit 기본 은행 인증을 사용합니다. 이는 제공업체와 무관한 제품으로, 사용자의 국가와 금융기관을 담당하는 지역 오픈뱅킹 벤더로 경로가 지정되며 Didit의 계약과 결제를 따릅니다. 값을 입력하면 이 애플리케이션이 자체 자격 증명을 연결한 마켓플레이스 제공업체를 지정합니다. 이 경우 세션은 귀하의 제공업체 계정에서 실행, 과금, 해지되며, Didit은 마켓플레이스 플랫폼 수수료만 청구합니다. 연결되지 않은 제공업체는 저장 시 거부됩니다. |

예시 `config` 객체입니다. 은행 인증이 켜져 있고 선택한 경로가 나열한 국가를 지원하는 계정의 예입니다.

```json theme={null}
{
  "bank_method_order": ["open_banking", "account_lookup"],
  "bank_countries": {
    "ESP": { "enabled": true, "institutions": "all" }
  },
  "bank_scopes": { "ownership": true },
  "bank_eligible_account_types": ["checking", "current"],
  "bank_name_match_threshold": 85,
  "bank_partial_match_floor": 70,
  "bank_partial_match_action": "REVIEW",
  "bank_no_match_action": "DECLINE"
}
```

> [!WARNING]
>
> `bank_countries`가 이 단계의 동작을 결정하며, 전역 목록이 아니라 노드가 실행되는 경로를 기준으로 검사됩니다. 해당 경로가 계좌 소유권을 확인할 수 없는 국가는 저장 시 거부되며 오류 메시지에 명시됩니다. 따라서 국가가 허용되었고 실행 시 건너뛸 것이라고 가정하지 말고 오류 메시지를 확인하십시오.

## AML

기능 값: `AML`.

KYC 개인 스크리닝에는 다음 필드를 사용합니다:

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `is_aml_ongoing_monitoring_enabled` | boolean | 지속적인 AML 모니터링을 활성화합니다. |
| `aml_score_approve_threshold` | integer | 승인 임계값입니다. |
| `aml_score_review_threshold` | integer | 검토 임계값입니다. |
| `aml_match_score_threshold` | integer | 가능한 일치 항목에 적용되는 일치 점수 임계값입니다. |
| `aml_name_weight` | integer | 이름 가중치입니다. AML 가중치를 하나라도 입력하면 이름, 생년월일, 국가 가중치의 합이 `100`이어야 합니다. |
| `aml_dob_weight` | integer | 생년월일 가중치입니다. |
| `aml_country_weight` | integer | 국가 가중치입니다. |
| `create_cases_on_hit` | boolean | 스크리닝에서 일치 항목이 반환되면 세션에서 분류하도록 남겨두는 대신 케이스를 자동으로 엽니다. 기본적으로 꺼져 있습니다. |
| `case_blueprint` | uuid | 자동으로 생성되는 케이스를 만들 때 사용할 케이스 블루프린트입니다. `create_cases_on_hit`와 함께 사용할 때만 의미가 있으며, 설정하지 않으면 계정 기본값이 사용됩니다. |
| `status_rules` | array | 선택 사항인 사용자 지정 상태 규칙입니다. |

KYB 기업 스크리닝에는 다음 필드를 사용합니다:

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `kyb_score_approve_threshold` | integer | 회사 AML 승인 임계값입니다. |
| `kyb_score_review_threshold` | integer | 회사 AML 검토 임계값입니다. |
| `kyb_enable_ongoing_monitoring` | boolean | KYB 지속적인 AML 모니터링을 활성화합니다. |
| `kyb_company_aml_match_score_threshold` | integer | 회사 AML 일치 점수 임계값입니다. |
| `kyb_company_aml_name_weight` | integer | 회사명 가중치입니다. 값을 입력하면 회사 AML 가중치의 합이 `100`이어야 합니다. |
| `kyb_company_aml_dob_weight` | integer | 설립일 또는 생년월일 가중치입니다. |
| `kyb_company_aml_country_weight` | integer | 국가 가중치입니다. |

### Document AI 단계로 추출한 주체 스크리닝

AML 단계는 보통 `OCR` 단계(개인)나 `KYB_REGISTRY` 단계(회사)에서 스크리닝 대상을 읽습니다. 세금 증명서나 설립 증서처럼 표준화되지 않은 문서를 다루며 `DOCUMENT_AI`만 추출 단계로 쓰는 워크플로에는 이 두 단계가 없으므로, 각 스크리닝 입력값이 어디에서 와야 하는지 명시해야 합니다.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `aml_field_sources` | object | 이 단계가 스크리닝하는 주체를 읽을 위치입니다. `source`는 값을 제공하는 출처를, `key`는 그 안의 값을 지정합니다. `document_ai`일 때는 Document AI 필드 키, `questionnaire`일 때는 설문 노드 ID, `expected_data`일 때는 `expected_details.<field>` 또는 `metadata.<key>`입니다. 매핑의 키(KEY)는 네 가지 스크리닝 입력값 중 하나입니다(`full_name`, `date_of_birth`, `nationality`, `document_number`). 회사의 경우 각각 법적 명칭, 설립일, 국가, 등록번호로 읽힙니다. 이 네 가지 중 하나로 키가 지정된 Document AI 필드는 자동으로 매핑되며, 의도적으로 저장되지 않습니다. 따라서 필드 이름을 바꿔도 오래된 매핑이 고정되지 않습니다. 명시적 매핑은 자동 매핑과 신분증 문서보다 우선합니다. 실행 시점에 아무 값도 가리키지 않는 매핑은 다른 값으로 대체하지 않고 입력값을 비워 둡니다. 기업(KYB) 워크플로에서는 `KYB_REGISTRY` 단계가 반환한 회사 정보가 기준입니다. 명시적 매핑만 그 입력값을 덮어쓸 수 있으며, 등기 기록에 자동 매핑을 추가로 적용하지 않습니다. 등록 단계가 없으면 매핑이 전체 신원 정보가 됩니다. 형식: `{"full_name"\|"date_of_birth"\|"nationality"\|"document_number": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<field>\|metadata.<key>"}}` |
| `aml_entity_type` | string | `person` 또는 `company`입니다. 개인(KYC) 워크플로에서는 기본값이 `person`이고, 기업(KYB) 워크플로에서는 기본값이 `company`입니다. `KYB_REGISTRY` 단계 없이 업로드된 문서에 명시된 기업을 스크리닝하려면 `company`로 설정하세요. 제공업체가 회사 기록을 검색하며, 일치 점수는 회사 기준으로 산정됩니다. |
| `aml_incomplete_data_action` | action | 전체 신원 정보(이름, 생년월일, 국가)보다 적은 정보로 스크리닝이 실행되었을 때의 판정입니다. 기본값은 `REVIEW`입니다. `NO_ACTION`은 이름만 있다는 것을 알고 있는 워크플로에서 축소된 데이터로 진행합니다. 스크리닝은 어느 경우에도 실행되고, 부분 데이터 로그도 어느 경우에도 기록됩니다. 이 설정은 상태에 미치는 영향만 결정합니다. |

예시 - 워크플로 어디에도 신분증 문서가 없는 상태에서 멕시코 *acta constitutiva*에 명시된 회사를 스크리닝하는 경우:

```json theme={null}
{
  "feature": "AML",
  "config": {
    "aml_entity_type": "company",
    "aml_field_sources": {
      "full_name": { "source": "document_ai", "key": "razon_social" },
      "document_number": { "source": "document_ai", "key": "rfc" },
      "date_of_birth": { "source": "document_ai", "key": "fecha_constitucion" },
      "nationality": { "source": "document_ai", "key": "pais" }
    },
    "aml_incomplete_data_action": "REVIEW"
  }
}
```

> [!WARNING]
>
> 앞에 `OCR` 단계와 `KYB_REGISTRY` 단계가 없으면, `AML` 단계는 `full_name`을 채울 수 있어야 합니다. 이름이 없으면 제공업체 검색을 할 수 없습니다. 아무것도 매핑하지 않거나, 상위 단계가 추출하지 않는 Document AI 키를 매핑하는 워크플로는 저장 시 거부됩니다. 스크리닝할 대상이 없는 상태로 저장되지 않습니다. AML 정밀도는 제공하는 식별자 수에 직접 좌우됩니다. 이름만으로 하는 스크리닝은 오탐이 많이 발생하는 원인입니다.

## 기기 및 IP 분석

기능 값: `IP_ANALYSIS`.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `ip_mismatch_action` | 작업 | IP 지리적 위치가 예상 데이터와 일치하지 않을 때의 작업입니다. |
| `ip_location_not_determined_action` | 작업 | 최종 사용자를 식별하는 IP 주소가 기록되지 않아 세션에 IP 위치 정보가 전혀 없는 경우의 판정입니다. 이 경우 국가, 도시, ISP, 좌표 및 시간대를 사용할 수 없으며, `ip_geofencing_by_country`, 문서 국가 비교, VPN/데이터 센터 검사를 실행할 수 없습니다. 기본값은 `NO_ACTION`이며, 이 값은 판정을 바꾸지 않고 세션에 `IP_LOCATION_NOT_DETERMINED` 경고를 계속 표시합니다. 위치를 확인할 수 없는 세션이 통과하면 안 되는 경우 `REVIEW` 또는 `DECLINE`으로 설정하십시오. |
| `vpn_detection_action` | 작업 | VPN 또는 프록시 사용이 감지되었을 때의 작업입니다. |
| `expected_ip_mismatch_action` | 작업 | IP가 예상 IP와 일치하지 않을 때의 작업입니다. |
| `duplicated_ip_action` | 작업 | IP가 의심스럽게 재사용되었을 때의 작업입니다. |
| `duplicated_device_action` | 작업 | 서로 다른 `vendor_data` 값을 가진 세션에서 같은 영구 기기 핑거프린트가 재사용되었을 때의 작업입니다. |
| `recovered_device_action` | 작업 | 영구 기기 ID가 변경된 후 v2 핑거프린트 복구를 통해 세션이 이전에 확인된 기기와 높은 신뢰도로 연결되었을 때의 작업입니다. |
| `is_ip_geofencing_enabled` | 불리언 | IP 지오펜싱 제한을 활성화합니다. `false`이면 `ip_geofencing_by_country`는 유지되지만 적용되지 않습니다. |
| `ip_geofencing_by_country` | 객체 | ISO-3 국가 코드를 키로 사용하는 국가별 IP 위치 규칙입니다: `{"USA": {"allowed": true, "states": {"California": {"allowed": false}}}}`. 주/지역 항목은 국가 플래그보다 우선하며, 목록에 없는 국가는 허용됩니다. |
| `ip_geofencing_action` | 작업 | 세션 IP가 허용되지 않은 국가 또는 주/지역에 있을 때의 작업입니다. 기본값은 `DECLINE`입니다. |
| `automation_detected_action` | 작업 | 세션이 사람이 아닌 자동화에 의해 구동되는 것으로 보일 때의 판정입니다. |
| `cross_org_fraud_device_action` | 작업 | 네트워크의 다른 조직에서 이 기기를 사기로 표시했을 때의 판정입니다. |
| `cross_org_fraud_ip_action` | 작업 | 네트워크의 다른 조직에서 이 IP를 사기로 표시했을 때의 판정입니다. |
| `device_app_tampered_action` | 작업 | 호스트 애플리케이션 바이너리가 변조된 것으로 보일 때의 판정입니다. |
| `device_blocklist_action` | 작업 | 기기가 조직의 차단 목록에 있을 때의 판정입니다. |
| `device_debugger_action` | 작업 | 호스트 애플리케이션에 디버거가 연결되어 있을 때의 판정입니다. |
| `device_emulator_action` | 작업 | 기기가 실제 하드웨어가 아닌 에뮬레이터일 때의 판정입니다. |
| `device_hooking_action` | 작업 | 런타임 후킹 또는 계측이 감지되었을 때의 판정입니다. |
| `device_integrity_missing_action` | 작업 | 플랫폼 기기 무결성 증명이 반환되지 않았을 때의 판정입니다. |
| `device_rooted_action` | 작업 | 기기가 루팅 또는 탈옥되었을 때의 판정입니다. |
| `multiple_devices_action` | 작업 | 세션이 두 개 이상의 기기에서 구동되었을 때의 판정입니다. |
| `device_liveness_attack_history_action` | 작업 | 같은 기기(영구 기기 ID로 일치)가 라이브니스 캡처가 공격으로 판정된 다른 사용자의 이전 세션에서 사용되었을 때의 작업입니다(경고 `DEVICE_LINKED_TO_LIVENESS_ATTACK`). 기본값은 `NO_ACTION`입니다. |
| `device_model_inconsistency_action` | 작업 | 같은 기기(영구 기기 ID로 일치)가 이전 세션에서 다른 기기 모델로 보고되었을 때의 작업입니다(경고 `DEVICE_MODEL_INCONSISTENT`). 기본값은 `NO_ACTION`입니다. |
| `status_rules` | 배열 | 선택 사항인 사용자 지정 상태 규칙입니다. |

예시:

```json theme={null}
{
  "feature": "IP_ANALYSIS",
  "config": {
    "vpn_detection_action": "REVIEW",
    "duplicated_device_action": "REVIEW",
    "recovered_device_action": "REVIEW",
    "is_ip_geofencing_enabled": true,
    "ip_geofencing_by_country": {
      "USA": { "allowed": true, "states": { "California": { "allowed": false } } },
      "RUS": { "allowed": false, "states": null }
    },
    "ip_geofencing_action": "DECLINE"
  }
}
```

고신뢰 복구 기기를 자동으로 거부하기 전에 모니터링하려는 경우 `duplicated_device_action`과 별도로 `recovered_device_action`을 사용하십시오. 복구 기기 일치는 사기 조직 탐지를 위해 설계되었지만 여전히 자체 트래픽을 기준으로 보정해야 하므로, 롤아웃 중에 이 방식이 유용합니다.

## 위치 확인

기능 값: `GEOLOCATION`.

인증하는 동안 사용자가 어디에 있는지 확인합니다. 기기 위치 또는 연결의 IP 위치를 기준으로, 허용 구역과 차단 구역, IP 위치, 문서 주소와 대조합니다.
단계의 동작 방식은 [위치 확인](https://docs.didit.me/ko/core-technology/location-verification/overview.md) 문서를, 판단 필드는 [보고서](https://docs.didit.me/ko/core-technology/location-verification/report-location-verification.md)를 참고하십시오.
문서 주소까지의 거리를 확인하려면 신분증 인증 또는 주소 증명 뒤에 배치하십시오. 거리는 주소가 등록되어 있을 때만 측정되기 때문입니다.
`geolocation_position_source`를 설정하지 않으면, IP 위치까지의 거리를 구하기 위해 같은 워크플로에 기기 및 IP 분석 단계가 있어야 합니다.
모든 키는 선택 사항입니다. `config`가 비어 있는 단계는 기기에 250m 이내 정확도의 위치를 요청하고, 120초보다 오래되지 않은 위치를 받으며, 사용자에게 3회의 시도 기회를 주고, 구역 규칙은 적용하지 않습니다.

각 탐지 결과에는 고유한 작업 키가 있습니다. 설정하지 않은 작업 키는 선택한 `geolocation_preset`의 기본값을 따르며, 프리셋을 선택하지 않았다면 아래에 나온 키별 기본값을 따릅니다.
불확실하거나 거부된 위치의 기본 작업은 `DECLINE`이 아닌 `REVIEW`입니다. 권한이 거부되었거나 반경이 넓다는 사실만으로는 사기의 증거가 되지 않기 때문입니다.
직접 설정한 작업은 항상 프리셋보다 우선합니다.
재생된 챌린지(`LOCATION_REPLAY_DETECTED`)와 기기 증명 실패(`LOCATION_INTEGRITY_FAILED`)는 항상 거부되며, 작업 키가 없습니다.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `geolocation_position_source` | 문자열 | 위치 정보의 출처입니다. `device_and_ip`는 기기 위치를 요청하고, 이를 제출한 연결의 IP 위치와 비교합니다(해당 IP가 아직 캐시되지 않았다면 IP 인텔리전스 조회를 수행합니다). 설정하지 않으면(기본값) 기기 위치를 요청하며, 이 키가 도입되기 전과 같이 세션의 기기 및 IP 분석 단계에서 관찰된 IP 위치와 비교합니다. 따라서 해당 단계가 없으면 거리를 구할 수 없으며, 연결을 조회하지도 않습니다. 예외는 VPN, 프록시 또는 Tor 탐지 결과에 따라 작업하는 노드(노드 고유의 작업 또는 프리셋)입니다. 이 경우 해당 탐지 결과를 위해 연결을 조회하고, `device_and_ip`와 마찬가지로 기기를 그 결과와 비교합니다. `device_only`는 IP 위치와 절대 비교하지 않으며, 해당 탐지 결과에 대해서만 연결을 조회합니다. `ip_only`는 사용자에게 묻지 않고, 대신 연결의 IP 위치를 판단합니다. 기준은 도시 수준, 반경 50km이며, 정확도, 최신성, 대략적 위치 허용에 관한 규칙은 적용되지 않습니다. `geolocation_areas`를 사용하면 해안 도시는 반경 내에 다른 국가가 없는 한 해당 국가 안에서 판단합니다. 기기에 위치를 요청하는 노드에서, 기기 위치가 없는 시도는 그에 해당하는 거부 또는 실패로 판단합니다. IP 위치가 이를 대신하지 않습니다. |
| `geolocation_preset` | 문자열 | 이 노드에서 설정하지 않은 모든 작업이 따르는 기본값입니다. `licensing`: 구역 밖이거나 차단 구역에 있거나, VPN, Tor 또는 에뮬레이터가 탐지되면 거부합니다. 프록시와 그 밖의 탐지 결과는 검토합니다. 기기 증명이 없으면 작업 없음으로 둡니다. `fraud_screening`: 라이선싱에서 거부되는 항목을 검토로 보낸다는 점만 다르고 나머지는 같습니다. null이면 기존의 오랜 기본값을 유지합니다. 직접 설정한 작업은 항상 우선합니다. |
| `geolocation_accuracy_mode` | 문자열 | 기기에 요청할 위치 정확도입니다. `precise`는 운영체제에 정밀 위치를 요청하며, 사용자가 대략적 위치만 허용하면 시도가 남아 있는 동안 다시 요청하고, 그 뒤에는 `geolocation_approximate_action`으로 판단합니다. `approximate_allowed`는 이 판단 없이 대략적 위치 허용을 수락합니다. `geolocation_max_accuracy_radius_m`은 두 경우 모두 적용됩니다. 설정하지 않으면 `precise`입니다. |
| `geolocation_max_accuracy_radius_m` | 정수 | 기기 위치가 유효하게 인정되기 위해 가질 수 있는 최대 불확실성 반경(미터)입니다. 10에서 50000미터 사이이며, 설정하지 않으면 250입니다. 이보다 넓은 위치, 또는 반경을 보고하지 않는 위치는 `geolocation_low_accuracy_behavior`의 설정대로 처리되고, `geolocation_low_accuracy_action`으로 판단합니다. `ip_only` 노드에는 기기 반경이 없으므로 이 값을 적용하지 않습니다. |
| `geolocation_max_accuracy_radius_unit` | 문자열 | 콘솔에서 `geolocation_max_accuracy_radius_m`을 표시하는 단위입니다. 표시용일 뿐입니다. 저장되는 값은 항상 미터이며, 어떤 규칙도 이 값에 의존하지 않습니다. 단계 데이터는 클라이언트가 같은 단위로 보여줄 수 있도록 이 값을 전달할 뿐입니다. |
| `geolocation_low_accuracy_behavior` | 문자열 | `geolocation_max_accuracy_radius_m`보다 넓은 위치이거나 반경이 없는 위치일 때의 동작입니다. `ask_again`(기본값)은 시도가 남아 있는 동안 사용자에게 다시 시도하도록 요청합니다. `fail`은 첫 번째 시도에서 단계를 종료합니다. |
| `geolocation_max_age_seconds` | 정수 | 서버가 수신할 때 기기 위치가 얼마나 오래된 것까지 허용되는지를 나타냅니다. 5초에서 3600초 사이이며, 설정하지 않으면 120초입니다. 이보다 오래된 위치는 시도가 남아 있는 동안 다시 요청하고, 그 뒤에는 `geolocation_stale_fix_action`으로 판단합니다. |
| `geolocation_timeout_seconds` | 정수 | 각 시도에서 클라이언트가 기기에서 위치를 찾도록 허용하는 시간(초)입니다. 서버는 이 값을 단계 데이터에 담아 전달할 뿐이며, 자체적으로 적용하지는 않습니다. 5초에서 120초 사이이며, 설정하지 않으면 20초입니다. 제한 시간 안에 위치를 찾지 못한 시도는 `timeout`으로 제출되며, 시도가 남아 있는 동안 다시 요청하고, 그 뒤에는 `geolocation_unavailable_action`으로 판단합니다. |
| `geolocation_max_attempts` | 정수 | 이 노드에서 사용자가 받을 수 있는 시도 횟수입니다. 1회에서 5회 사이이며, 설정하지 않으면 3회입니다. 사용자가 아직 바꿀 수 있는 시도(거부, 넓거나 오래되었거나 대략적인 위치, 또는 노드가 작업하는 구역 또는 익명화 도구 탐지 결과)는 시도가 남아 있는 동안 다시 요청하며, 마지막 시도가 단계의 결과를 결정합니다. 조작된 위치, 또는 노드가 작업하는 에뮬레이터는 이를 보고한 시도에서 단계를 종료합니다. |
| `geolocation_allow_qr_handoff` | 불리언 | 단계가 열려 있는 동안 QR 코드로 휴대폰에서 계속 진행할 수 있도록 제안합니다(단계 데이터의 `allow_qr_handoff`, 각 제출 응답의 `can_handoff`). 네이티브 SDK는 이미 휴대폰에서 실행되므로 코드를 표시하지 않습니다. 기본적으로 켜져 있습니다. |
| `geolocation_allow_skip` | 불리언 | 소개 화면이나 재시도 화면에서 언제든 위치 정보 없이 진행할 수 있도록 허용합니다(`skipped: true`). 건너뛰기는 단계를 종료하며 `geolocation_unavailable_action`으로 판단합니다. 다만 `continue_without_location` `geolocation_refusal_path`에서 거부에 대한 응답으로 건너뛴 경우에는 해당 거부로 기록됩니다. 기본적으로 꺼져 있습니다. |
| `geolocation_deep_link_enabled` | boolean | `deep_link_enabled`로 단계 데이터에 전달되어, 대신 고객 본인의 앱을 열도록 제안합니다. 서버는 이 값에 어떤 규칙도 적용하지 않습니다. 기본값은 꺼짐입니다. |
| `geolocation_refusal_path` | string | 위치 접근이 거부되었을 때 제공되는 진행 방식입니다. `retry_then_handoff`(기본값)는 시도 횟수가 남아 있는 동안 다시 요청하고 전화 전환을 제안합니다. `continue_without_location`은 거부 사실을 기록한 채 사용자가 계속 진행하게 합니다. `end_session`은 첫 거부 시 단계와 세션을 종료합니다. 이 방식을 사용하려면 `geolocation_permission_denied_action`이 검토 또는 거부로 설정되어 있어야 하며, 워크플로에 거부됨, 검토 중 또는 최종 결정으로 끝나는 결과가 있어야 합니다. 세션의 결정은 실행된 단계를 바탕으로 내려지며 승인됨이 되는 경우는 없습니다. 해당 결정으로 끝날 수 없는 워크플로에서는 다른 비승인 종료 결과를 사용합니다(검토 중 대신 거부됨, 거부됨 대신 검토 중). |
| `is_geolocation_geofencing_enabled` | boolean | 영역 규칙을 켭니다. `geolocation_areas` 또는 이전 방식인 `geolocation_geofencing_by_country`는 이 값이 true일 때만 적용되며, 그때에만 단계 데이터에 `available_areas`가 표시됩니다. 기본값은 꺼짐입니다. 이 값이 켜져 있으면 `geolocation_areas` 목록에 허용 영역이 최소 하나 있어야 합니다. |
| `geolocation_areas` | array | 허용 영역과 차단 영역입니다. `is_geolocation_geofencing_enabled`가 true일 때 적용됩니다. 허용 영역 안의 위치만 통과하며, 차단 영역은 허용 영역보다 항상 우선합니다. 위치는 정확도 원 전체를 기준으로 판단합니다. 결과를 결정하는 경계선과 원이 교차하면 밖으로 간주하지 않고 판단을 보류합니다. 국가 또는 지역은 다른 육지가 시작되는 지점에서 끝나며, 해안선에서 끝나지 않습니다. 단순화된 해안선이 잘라낸 해안가나 부두처럼 어떤 육지 윤곽에도 속하지 않는 위치는, 그 반경에서 12해리를 더한 범위 안에 있는 모든 국가 또는 지역에 대해 판단을 보류합니다. `id`는 분기 규칙과 `geolocation.inside_areas` / `geolocation.blocked_areas`가 참조하는 값입니다. `kind`는 형태를 정합니다. 공개된 윤곽이 있는 국가 전체(`country`, ISO 3166-1 alpha-3 코드 사용)를 지정하거나, 다른 국가의 일부로 그려지는 영역은 `region`으로 지정합니다. 예를 들어 레위니옹은 `FR-RE`, 보네르, 신트외스타티위스, 사바는 `NL-BQ1`부터 `NL-BQ3`으로 지정합니다. `region`은 공개된 경계가 있는 한 국가의 ISO 3166-2 코드를 사용합니다. `circle`은 반경 1km에서 500km 사이이며, `polygon`은 3개에서 200개 점으로 이루어지고 변이 서로 교차하거나 맞닿지 않는 고리 모양이어야 합니다. 영역은 최대 50개까지 가능하며 id는 고유해야 합니다. 영역 확인이 켜져 있는 동안 허용 영역이 최소 하나 있어야 합니다. `geolocation_geofencing_by_country`와 함께 사용할 수 없습니다. |
| `geolocation_geofencing_by_country` | object | 기기 자체 위치에 대한 국가 및 지역 허용/거부 규칙입니다. `is_geolocation_geofencing_enabled`가 true일 때에만 적용됩니다. 형식은 IP 분석의 `ip_geofencing_by_country`와 같지만, 위치가 제공업체의 도시 라벨이 아니라 행정구역으로 확인되므로 `states` 키는 주 이름이 아니라 ISO 3166-2 코드(`US-NJ`)를 사용합니다. 목록에 없는 국가는 허용됩니다. 공개된 ISO 3166-2 경계가 없는 국가에 대한 지역 규칙은 조용히 무시되지 않고 거부됩니다. |
| `geolocation_ip_distance_km` | integer | 기기 위치와 IP 위치가 얼마나 떨어져 있어도 되는지를 킬로미터 단위로 정합니다. 두 불확실성 반경을 뺀 뒤 이 거리를 넘으면 `geolocation_ip_distance_action`이 적용됩니다. 키를 생략하면 200이며, null로 설정하면 비교를 끕니다. `geolocation_position_source`가 `device_and_ip`이거나 설정되지 않은 노드만 비교하며, 이 키가 비교할 IP 위치를 정합니다. |
| `geolocation_ip_distance_unit` | string | 콘솔이 `geolocation_ip_distance_km`을 표시하는 단위입니다. 표시용이며, 저장되는 값은 항상 킬로미터이고 어떤 규칙도 이 값에 의존하지 않습니다. |
| `geolocation_document_distance_km` | integer | `ip_only` 노드에서는 IP 위치이고, 그 외에는 위치가 `geolocation_document_distance_basis`가 가리키는 주소에서 얼마나 떨어져 있어도 되는지를 킬로미터 단위로 정합니다. 이 거리를 넘으면 `geolocation_document_distance_action`이 적용됩니다. 설정하지 않았거나 null이면(기본값) 비활성화됩니다. |
| `geolocation_document_distance_unit` | string | 콘솔이 `geolocation_document_distance_km`을 표시하는 단위입니다. 표시용이며, 저장되는 값은 항상 킬로미터이고 어떤 규칙도 이 값에 의존하지 않습니다. |
| `geolocation_document_distance_basis` | string | `geolocation_document_distance_km`을 측정할 기준 주소입니다. `document`(기본값)는 신분증의 주소를 쓰고 없으면 주소 증명을 씁니다. `proof_of_address`는 주소 증명만 씁니다. `declared`는 세션 생성 시 제공된 `expected_details.address`를 지오코딩하여 씁니다. |
| `geolocation_travel_tolerance_enabled` | boolean | 같은 사람(같은 `vendor_data`)이 지난 `geolocation_travel_max_days`일 안에 해당 주소의 `geolocation_travel_usual_area_km` 반경 안에서 확인된 적이 있으면, 주소로부터의 거리를 예외로 인정합니다. VPN, 스푸핑된 위치, 차단 영역 또는 허용 영역 밖에 있는 경우에는 결코 예외로 인정하지 않습니다. 기기가 직접 측정한 위치만 그곳에서 확인된 것으로 간주합니다. 모의 또는 시뮬레이션된 위치, 에뮬레이터, 실패한 증명은 결코 그렇게 간주되지 않습니다. |
| `geolocation_travel_usual_area_km` | integer | 사용자의 평소 생활권으로 간주되는 주소 주변 반경입니다. 10km에서 500km 사이이며, 설정하지 않으면 100입니다. |
| `geolocation_travel_max_days` | integer | 평소 생활권에서 확인된 뒤 멀리 떨어진 위치가 여전히 이동으로 인정되는 기간입니다. 1일에서 90일 사이이며, 설정하지 않으면 14입니다. |
| `geolocation_consecutive_mismatch_count` | integer | 이번 확인과 같은 사람(같은 `vendor_data`)의 이전 확인들이 이 횟수만큼 연속으로 허용 영역 밖, 차단 영역 안, 또는 주소에서 너무 멀리 떨어진 곳에서 이루어졌으면 LOCATION\_CONSECUTIVE\_MISMATCHES를 발생시킵니다. 아무것도 비교하지 않은 확인은 연속 기록을 늘리거나 끊지 않으며, 기기가 측정하지 않은 위치(모의 또는 시뮬레이션된 위치, 에뮬레이터, 실패한 증명)도 마찬가지입니다. 값은 2에서 10 사이이며, null(기본값)이면 비활성화됩니다. |
| `geolocation_approximate_action` | action | 사용자가 `geolocation_accuracy_mode`에서 정밀 위치를 요구했는데 대략적 위치를 허용한 경우의 판정입니다. 기본값은 `REVIEW`입니다. |
| `geolocation_blocked_area_action` | action | 위치와 정확도 원 전체가 `geolocation_areas`의 차단 영역 안에 들어가는 경우의 판정입니다. 기본값은 거부입니다. |
| `geolocation_consecutive_mismatch_action` | 작업 | `geolocation_consecutive_mismatch_count`회 연속으로 불일치가 발생하면 적용되는 판정입니다. 기본값은 검토입니다. |
| `geolocation_document_distance_action` | 작업 | 기기 위치가 `geolocation_document_distance_km`보다 문서 주소에서 더 멀리 떨어져 있을 때 적용되는 판정입니다. 주소는 대략적으로 지오코딩되므로 이 신호는 약한 신호입니다. 기본값은 `REVIEW`입니다. |
| `geolocation_emulator_action` | 작업 | 위치를 공유한 앱이 에뮬레이터에서 실행 중이라고 보고했을 때 적용되는 판정입니다. 브라우저는 이를 보고할 수 없습니다. 조치 없음으로 설정되어 있지 않다면 해당 시도에서 단계가 종료됩니다. 기기는 바뀌지 않으므로 다시 확인해도 결과는 달라지지 않습니다. 설정 또는 프리셋에서 달리 지정하지 않으면 조치 없음입니다. |
| `geolocation_geofence_undetermined_action` | 작업 | 정확도 원이 경계에 닿아 위치가 울타리 안인지 밖인지 정할 수 없을 때 적용되는 판정입니다. 불확실성은 울타리 밖으로 보고되지 않습니다. 기본값은 `REVIEW`입니다. |
| `geolocation_geofencing_action` | 작업 | 기기 위치와 그 불확실성 원 전체가 `geolocation_geofencing_by_country` 밖에 있을 때 적용되는 판정입니다. 기본값은 `DECLINE`입니다. |
| `geolocation_integrity_missing_action` | 작업 | 네이티브 클라이언트가 기기 증명 토큰 없이 위치를 제출했을 때 적용되는 판정입니다. 기본값은 조치 없음입니다. 웹 클라이언트는 어떤 브라우저도 증명할 수 없으므로 누락이 아니라 미지원으로 기록됩니다. |
| `geolocation_ip_distance_action` | 작업 | 두 불확실성 반경을 뺀 뒤에도 기기 위치와 세션의 IP 위치 사이 거리가 `geolocation_ip_distance_km`보다 멀 때 적용되는 판정입니다. 기본값은 `REVIEW`입니다. |
| `geolocation_low_accuracy_action` | 작업 | 어떤 시도에서도 필요한 정밀도를 확보하지 못했을 때 적용되는 판정입니다. 가장 나은 위치의 불확실성 반경이 `geolocation_max_accuracy_radius_m`보다 넓거나, 반경을 전혀 보고하지 않은 경우입니다. 반경이 없는 위치는 제한을 충족한 것으로 간주되지 않습니다. 기본값은 `REVIEW`입니다. |
| `geolocation_mock_location_action` | 작업 | 운영 체제가 위치를 측정값이 아닌 시뮬레이션된 값으로 보고했을 때 적용되는 판정입니다(Android 모의 위치 제공자, iOS 소프트웨어 시뮬레이션). 기본값은 `REVIEW`입니다. |
| `geolocation_permission_denied_action` | 작업 | 허용된 모든 시도에서 사용자가 위치 권한 요청을 거부하거나 닫았을 때 적용되는 판정입니다. 기본값은 검토입니다. 거부는 사기 신호가 아니라 선택이기 때문입니다. |
| `geolocation_proxy_action` | 작업 | 위치를 공유한 연결이 공개, 익명 또는 프라이빗 릴레이 프록시를 거칠 때 적용되는 판정입니다. 설정 또는 프리셋에서 달리 지정하지 않으면 조치 없음입니다. |
| `geolocation_stale_fix_action` | 작업 | 서버가 위치를 받기 `geolocation_max_age_seconds`초보다 더 전에 측정된 위치일 때 적용되는 판정입니다. 기본값은 `REVIEW`입니다. |
| `geolocation_tor_action` | 작업 | 위치를 공유한 연결이 Tor 출구 노드일 때 적용되는 판정입니다. 설정 또는 프리셋에서 달리 지정하지 않으면 조치 없음입니다. |
| `geolocation_unavailable_action` | 작업 | 위치를 얻지 못했을 때 적용되는 판정입니다. 위치 서비스가 꺼져 있거나 제한된 경우, 측위 시스템이 아무것도 반환하지 않은 경우, 시도가 시간 초과된 경우, 사용자가 단계를 건너뛴 경우, 또는 클라이언트가 너무 오래되어 이를 지원하지 않는 경우를 포함합니다. 기본값은 `REVIEW`입니다. |
| `geolocation_vpn_action` | 작업 | 위치를 공유한 연결이 상용 VPN일 때 적용되는 판정입니다. 조치 없음으로 설정되어 있지 않다면, 시도가 남아 있는 동안 사용자에게 VPN을 끄고 다시 확인하라는 안내가 표시됩니다. 설정 또는 프리셋에서 달리 지정하지 않으면 조치 없음입니다. |
| `status_rules` | 배열 | 선택 사항인 사용자 지정 상태 규칙입니다. [위치 인증 보고서](https://docs.didit.me/ko/core-technology/location-verification/report-location-verification.md#상태-규칙-및-분기용-필드)에 나열된 `geolocation.*` 필드를 대상으로 지정할 수 있습니다. |

### 영역 형태

`geolocation_areas`의 각 항목에는 `id`가 있습니다. 이 값은 `A-Z a-z 0-9 _ -` 문자로 이루어진 1\~64자이며 목록 안에서 고유해야 합니다. 선택 사항인 `label`(최대 80자), `type`(`allowed` 또는 `blocked`), 그리고 형태를 정하는 `kind`도 있습니다.

| `kind` | 추가 필드 | 의미 |
| - | - | - |
| `country` | `country`(ISO 3166-1 alpha-3) | 공개된 외곽선이 있는 국가 전체입니다. |
| `region` | `country`, `regions`(해당 국가의 ISO 3166-2 코드) | 공개된 경계가 있는 한 국가의 하나 이상의 하위 행정구역입니다. |
| `circle` | `center`(`latitude`, `longitude`), `radius_km`(1\~500) | 중심에서 반경 이내의 모든 지점입니다. |
| `polygon` | `points`(`latitude`, `longitude`로 이루어진 3\~200개 항목) | 변이 서로 교차하거나 닿지 않는 닫힌 고리입니다. |

목록에는 최대 50개의 영역을 담을 수 있으며, `is_geolocation_geofencing_enabled`가 `true`인 동안에는 `allowed` 영역이 최소 하나 있어야 합니다.
`geolocation_areas`와 `geolocation_geofencing_by_country`는 함께 보낼 수 없습니다. `geolocation_refusal_path: "end_session"`을 사용하려면 `geolocation_permission_denied_action`이 `REVIEW` 또는 `DECLINE`이어야 합니다.
API는 결코 일치할 수 없는 영역(예: 공개된 경계가 없는 국가의 하위 행정구역)을 저장하지 않고 거부합니다.

예시:

```json theme={null}
{
  "feature": "GEOLOCATION",
  "config": {
    "geolocation_position_source": "device_and_ip",
    "geolocation_preset": "licensing",
    "geolocation_max_accuracy_radius_m": 250,
    "geolocation_max_attempts": 3,
    "is_geolocation_geofencing_enabled": true,
    "geolocation_areas": [
      { "id": "spain", "label": "Spain", "type": "allowed", "kind": "country", "country": "ESP" },
      { "id": "ceuta-melilla", "type": "blocked", "kind": "region", "country": "ESP", "regions": ["ES-CE", "ES-ML"] }
    ],
    "geolocation_ip_distance_km": 200,
    "geolocation_ip_distance_action": "REVIEW",
    "geolocation_vpn_action": "DECLINE"
  }
}
```

## 주소 증명

기능 값: `PROOF_OF_ADDRESS`.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `poa_documents_allowed` | 객체 | ISO3 국가 코드를 POA 문서 유형 설정에 매핑합니다. 유효한 문서 유형을 하나 이상 활성화해야 합니다. |
| `poa_languages_allowed` | 객체 | ISO 639-1 언어 코드를 `0` 또는 `1`에 매핑합니다. 언어를 하나 이상 활성화해야 합니다. |
| `poa_name_or_address_mismatch_action` | 작업 | 이름 또는 주소가 예상 데이터와 일치하지 않을 때의 작업입니다. |
| `poa_document_issues_action` | 작업 | 문서에 품질 또는 추출 문제가 있을 때의 작업입니다. |
| `poa_max_attempts_exceeded_action` | 제한된 작업 | 사용자가 재시도 횟수를 초과했을 때의 작업입니다. `DECLINE` 또는 `REVIEW` 중 하나를 사용해야 합니다. |
| `poa_document_authenticity_action` | 제한된 작업 | 진위 검사에 실패했을 때의 작업입니다. `DECLINE` 또는 `REVIEW` 중 하나를 사용해야 합니다. |
| `poa_document_unproven_text_replacement_action` | 작업 | 텍스트 필드가 비워진 뒤 다른 글꼴로 다시 입력되었고, 파일에 내용이 변경되었는지 여부를 증명하는 근거가 없을 때의 작업입니다(`POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`). |
| `poa_unsupported_document_type_action` | 작업 | 문서 유형이 지원되지 않을 때의 작업입니다. |
| `poa_unsupported_language_action` | 작업 | 문서 언어가 지원되지 않을 때의 작업입니다. |
| `poa_issuer_not_identified_action` | 작업 | 문서 발급 기관을 식별할 수 없을 때의 작업입니다. |
| `poa_issue_date_not_detected_action` | 작업 | 발급일이 없을 때의 작업입니다. |
| `poa_unparsable_or_invalid_address_action` | 작업 | 주소가 올바르지 않거나 분석할 수 없을 때의 작업입니다. |
| `address_validation_enabled` | 불리언 | 이 단계가 읽는 주소(증명 서류에 인쇄된 주소이며, 문서 검사를 통과한 업로드만 검증됨)를 우편 참조 데이터와 대조해 검증합니다. 주소가 실제로 존재하는지 확인하고 정규화하며, 주소를 사람과 연결하지는 않습니다. 결과는 결정의 해당 단계 `address_validation` 객체에 담깁니다. **검증된 주소당 \$0.10이 청구되며**, 검증을 실행할 수 없는 경우(`unavailable`)에는 무료입니다. 기본적으로 꺼져 있습니다. |
| `address_not_verified_action` | 작업 | 주소 검증이 주소를 건물 단위까지 확인하지 못했을 때의 작업입니다(`ADDRESS_NOT_VERIFIED`: `partially_verified` 또는 `not_verified`). `address_validation_enabled`가 켜져 있을 때에만 적용됩니다. 기본값은 `NO_ACTION`이며, 이 경우 경고만 기록합니다. |
| `poa_name_match_score_threshold` | 정수 | 이름 일치 임계값입니다. |
| `poa_max_retry_attempts` | 정수 | 재시도 한도이며, `2`에서 `5`까지입니다. |
| `status_rules` | 배열 | 선택 사항인 사용자 지정 상태 규칙입니다. |

## 설문지

기능 값: `QUESTIONNAIRE`.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `questionnaire_uuid` | UUID | 필수입니다. `POST /v3/questionnaires/`가 반환한 `questionnaire_id`를 사용해야 합니다. |
| `review_questionnaire_manually` | 불리언 | 설문 응답을 수동 검토로 보냅니다. |
| `status_rules` | 배열 | 선택 사항인 사용자 지정 상태 규칙입니다. `questionnaire.answers.<question_id>` 필드를 대상으로 지정할 수 있습니다. |

## KYB 법인 등기부

기능 값: `KYB_REGISTRY`.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `kyb_accepted_countries` | 객체 | 기업 등기부 조회를 위한 레거시 ISO3 국가 허용 목록입니다. `kyb_registry_countries_config`로 대체되었습니다. 여전히 읽을 수 있고, 기존 워크플로의 경우 여전히 이 설정에서 파생되지만, 새 워크플로를 구성하는 방식은 더 이상 아닙니다. |
| `kyb_manual_company_action` | 작업 | 회사를 수동으로 처리해야 할 때의 작업입니다. |
| `kyb_registry_fields_config` | 객체 | 호스팅 흐름의 등기부 양식에서 필드별 표시 여부와 필수 여부를 설정합니다. 아래 내용을 참조합니다. |
| `kyb_registry_countries_config` | 객체 | 국가별 등기부 라우팅을 설정하며, 형식은 `{"<ISO2>": {"enabled": bool, "tier": "basic" \| "shareholders" \| "ubo"}}`입니다. 활성화된 각 국가는 회사를 선택할 때 청구되는 데이터 등급(tier)을 지정합니다(`basic`은 Lite 등급입니다). 해당 국가에 대해 [요금 endpoint](https://docs.didit.me/ko/getting-started/kyb-registry-pricing.md)가 사용 가능하다고 표시한 등급만 활성화할 수 있습니다. 국가는 최소 하나 이상 활성화해야 합니다. 아무 곳도 검색하지 않는 등기부 확인은 거부됩니다. 수동으로 입력한 회사는 별도로 청구되며 이 설정을 사용하지 않습니다. |
| `kyb_registry_monitoring_enabled` | 불리언 | Shareholders 또는 UBO 결과를 받은 후에도 회사의 등기부 기록을 지속적으로 모니터링합니다. 상태, 임원, 소유권 또는 주소가 변경되면 세션이 검토 단계로 되돌아가고 webhook을 발생시킵니다. 등기부 제공업체가 모니터링을 제공하는 경우에만 사용할 수 있습니다. 회사당 연간 USD 2.00이며 언제든지 취소할 수 있습니다. 기본적으로 꺼져 있습니다. |
| `kyb_vat_invalid_action` | 작업 | 회사의 VAT 번호가 EU VIES 검증에 실패했을 때의 작업입니다. 기본값은 `REVIEW`입니다. |
| `kyb_vat_unverified_action` | 작업 | VIES를 사용할 수 없어 VAT 번호를 검증할 수 없을 때의 작업입니다. 기본값은 `NO_ACTION`입니다. |
| `status_rules` | 배열 | 선택 사항인 사용자 지정 상태 규칙입니다. |

`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`만 필수이고 다른 모든 필드는 선택 사항입니다.

```json theme={null}
{
  "kyb_registry_fields_config": {
    "registration_number": { "enabled": true, "required": true },
    "incorporation_date": { "enabled": true, "required": true },
    "vat_number": { "enabled": true, "required": false },
    "control_scheme": { "enabled": false, "required": false }
  }
}
```

설정 가능한 필드 키: `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`. 최종 사용자 동작은 [설정 가능한 등기부 양식 필드](https://docs.didit.me/ko/business-verification/company-data.md#설정-가능한-법인-등기부-양식-필드)를 참조하고, `vat_number`와 `tax_number`의 검사 방식은 [VAT 및 납세자 번호 검증](https://docs.didit.me/ko/business-verification/company-data.md#vat-및-납세자-번호-검증)을 참조합니다.

## KYB 문서

기능 값: `KYB_DOCUMENTS`.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `kyb_required_document_groups` | 객체 또는 배열 | 필수. 필수 KYB 문서 그룹입니다. |
| `kyb_document_subtype_config` | 객체 | 문서 하위 유형별 활성화 및 기간 설정입니다. |
| `kyb_document_tampering_action` | 제한된 작업 | 변조가 감지되었을 때의 작업입니다. `DECLINE` 또는 `REVIEW`를 사용합니다. |
| `kyb_document_unproven_text_replacement_action` | 작업 | 회사 문서의 텍스트 필드가 지워진 뒤 다른 글꼴로 다시 입력되었고, 파일에 내용이 변경되었는지 여부를 증명하는 근거가 없을 때의 작업입니다(`KYB_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`). |
| `kyb_document_critical_mismatch_action` | 제한된 작업 | 중요한 문서 불일치에 대한 작업입니다. `DECLINE` 또는 `REVIEW`를 사용합니다. |
| `kyb_document_non_critical_mismatch_action` | 작업 | 중요하지 않은 문서 불일치에 대한 작업입니다. |
| `kyb_document_age_action` | 작업 | 문서 기간 규칙을 충족하지 못했을 때의 작업입니다. |
| `kyb_document_max_retry_attempts` | 정수 | KYB 문서의 재시도 횟수 한도입니다. |
| `kyb_document_max_attempts_exceeded_action` | 제한된 작업 | 최대 시도 횟수를 초과했을 때의 작업입니다. `DECLINE` 또는 `REVIEW`를 사용합니다. |
| `status_rules` | 배열 | 선택 사항인 사용자 지정 상태 규칙입니다. |

## KYB 주요 인물

기능 값: `KYB_KEY_PEOPLE`.

| 설정 필드 | 유형 | 설명 |
| - | - | - |
| `kyb_ubo_ownership_threshold` | 정수 | UBO 지분 임계값이며, `0`부터 `100`까지입니다. |
| `kyb_shareholder_ownership_threshold` | 정수 | 주주 지분 임계값이며, `0`부터 `100`까지입니다. `kyb_ubo_ownership_threshold`보다 높을 수 없습니다. |
| `kyb_key_people_ownership_required` | 불리언 | 제출된 모든 주요 인물에 지분율을 입력하도록 요구합니다. 제출 시점에 적용되며, 호스팅 인증 페이지에 전달되어 해당 필드를 필수로 표시합니다. 기본값은 `false`입니다. |
| `kyb_require_ubo_kyc` | 불리언 | UBO가 개인 인증 워크플로를 완료하도록 요구합니다. |
| `kyb_ubo_verification_workflow` | UUID | `kyb_require_ubo_kyc`가 `true`일 때 필수입니다. 같은 애플리케이션 내의 KYB가 아닌 워크플로를 참조해야 합니다. |
| `kyb_require_officer_kyc` | 불리언 | 임원이 개인 인증을 완료하도록 요구합니다. |
| `kyb_shareholder_verification_workflow` | UUID | 주주를 위한 개인 인증 워크플로입니다. |
| `kyb_officer_verification_workflow` | UUID | 임원을 위한 개인 인증 워크플로입니다. |
| `kyb_require_corporate_ubo_kyb` | 불리언 | 법인 UBO가 KYB를 완료하도록 요구합니다. |
| `kyb_corporate_ubo_verification_workflow` | UUID | `kyb_require_corporate_ubo_kyb`가 `true`일 때 필수입니다. 같은 애플리케이션 내의 KYB 워크플로를 참조해야 합니다. |
| `kyb_reject_if_ubo_rejected` | 불리언 | 필수 UBO 인증이 거부되면 기업을 거부합니다. |
| `kyb_wait_for_all_ubos` | 불리언 | KYB 세션을 결정하기 전에 필수 UBO 인증이 모두 끝날 때까지 기다립니다. |
| `kyb_role_config` | 객체 또는 배열 | 역할별 설정입니다. 필수 KYC 역할에는 각각 `verification_workflow`가 포함되어야 합니다. |
| `kyb_reuse_verified_individuals` | 불리언 | 가능한 경우 이미 인증된 개인을 재사용합니다. |
| `kyb_notify_parties_by_email` | 불리언 | 초대된 주요 인물에게 이메일 알림을 보냅니다. |
| `kyb_key_people_company_fields` | 객체 | CORPORATE 주요 인물에 대해 수집할 회사 정보입니다. `kyb_key_people_person_fields`와 같은 설명자 목록 형식과 규칙을 따릅니다. 형식: `[{"key": "<field key>", "label": "<label>", "type": "text"\|"number"\|"date"\|"phone"\|"email", "required": true\|false, "custom": true\|false}]`. |
| `kyb_key_people_document_mismatch_action` | 작업 | 주요 인물의 문서가 해당 인물에 대해 선언된 정보와 일치하지 않을 때의 결정입니다. |
| `kyb_key_people_person_fields` | 객체 | 개인 주요 인물에 대해 수집할 개인 정보입니다. 객체가 아니라 순서가 있는 목록 형식의 필드 설명자입니다. `key`는 필수이며 비어 있을 수 없습니다. `type`은 text, number, date, phone, email 중 하나여야 합니다. `custom`은 기본 제공 필드가 아니라 고객이 추가한 필드를 표시합니다. 형식: `[{"key": "<field key>", "label": "<label>", "type": "text"\|"number"\|"date"\|"phone"\|"email", "required": true\|false, "custom": true\|false}]`. |
| `kyb_key_people_prefill_from_registry` | 불리언 | 법인 등기부 결과로 주요 인물 목록을 미리 채웁니다. 고객은 모든 임원과 주주를 직접 입력하는 대신 확인하고 수정하면 됩니다. |
| `status_rules` | 배열 | 선택 사항인 사용자 지정 상태 규칙입니다. |

## Document AI

기능 값: `DOCUMENT_AI`.

사용자에게 하나 이상의 문서를 요청하고, 비전 모델을 사용해 정의한 필드를 추출합니다. 구성된 각 필드는 분기에 사용할 수 있는 값 `document_ai.<key>`가 되며, 단계의 결과는 `document_ai.status`입니다.

| 구성 필드 | 유형 | 설명 |
| - | - | - |
| `document_ai_documents` | array | 필수. 요청할 문서 목록(최대 `3`개)입니다. 각 항목은 문서 객체입니다(아래 참조). |
| `document_ai_unreadable_document_action` | action | 문서를 읽을 수 없거나 데이터를 추출할 수 없을 때의 작업입니다. |
| `document_ai_missing_required_fields_action` | action | 필수 필드를 추출할 수 없을 때의 작업입니다. |
| `document_ai_document_tampering_action` | restricted action | 문서에 변조 흔적이 있을 때의 작업입니다. `DECLINE` 또는 `REVIEW`를 사용하십시오. |
| `document_ai_name_mismatch_action` | action | 추출된 성명이 검증된 신원과 일치하지 않을 때의 작업입니다. `is_full_name`으로 표시된 필드가 필요합니다. |
| `document_ai_unsupported_file_action` | action | 업로드된 파일 형식이 지원되지 않을 때의 작업입니다. |
| `document_ai_max_attempts_exceeded_action` | restricted action | 사용자가 재시도 횟수를 초과했을 때의 작업입니다. `DECLINE` 또는 `REVIEW`를 사용하십시오. |
| `document_ai_name_match_score_threshold` | integer | 추출된 성명이 검증된 신원과 일치하기 위한 최소 점수(`0`–`100`)입니다. 이 값보다 낮으면 `document_ai_name_mismatch_action`이 적용됩니다. |
| `document_ai_max_retry_attempts` | integer | 재시도 한도이며, `2`에서 `5` 사이입니다. |
| `status_rules` | array | 선택 사항인 사용자 지정 상태 규칙입니다. `document_ai.<key>` 필드를 대상으로 지정할 수 있습니다. |

`document_ai_documents`의 각 항목은 다음과 같은 문서입니다.

| 문서 필드 | 유형 | 설명 |
| - | - | - |
| `document_key` | string | 필수. 문서의 고정 식별자이며, 단계 안에서 고유해야 합니다. |
| `title` | string | 필수. 사용자에게 표시되는 제목입니다. |
| `description` | string | 필수. 사용자에게 어떤 문서를 업로드해야 하는지 알려 주는 안내입니다. |
| `title_i18n` | object | 선택 사항. 로캘 코드별 번역된 제목을 매핑하는 객체입니다(예: `{ "es": "Comprobante de fondos" }`). |
| `description_i18n` | object | 선택 사항. 로캘 코드별 번역된 설명을 매핑하는 객체입니다. |
| `fields` | array | 필수. 추출할 필드 목록(최소 하나)입니다. 필드 키는 문서 안에서 고유해야 합니다. |

문서의 `fields`에 있는 각 항목은 다음과 같은 필드입니다.

| 필드 | 유형 | 설명 |
| - | - | - |
| `key` | string | 필수. 추출된 값의 고정 JSON 키이며, 문서 안에서 고유해야 합니다. `document_ai.<key>`로 분기할 때 사용합니다. |
| `name` | string | 필수. 사람이 읽을 수 있는 필드 레이블입니다. |
| `name_i18n` | object | 선택 사항. 로캘 코드별 번역된 필드 이름을 매핑하는 객체입니다. |
| `instruction` | string | 선택 사항. 이 필드에서 정확히 무엇을 추출해야 하는지 모델에 알려 주는 지시문입니다. |
| `type` | string | 필드 유형: `text`, `number` 또는 `date`. 기본값은 `text`입니다. |
| `required` | boolean | 필드가 반드시 있어야 하는지 여부입니다. 기본값은 `false`입니다. `true`이고 값이 없으면 `document_ai_missing_required_fields_action`이 적용됩니다. |
| `is_full_name` | boolean | 선택 사항이며 기본값은 `false`입니다. 값이 문서 소지자의 성명인 필드를 표시하며, 이 값은 검증된 신원(신분증 인증 이름 또는 세션에 설정된 예상 정보)과 비교됩니다. 문서당 **최대 하나의 필드만** `true`로 설정할 수 있으며, 이 설정은 **필수가 아닙니다**. 문서에서 아무 필드도 표시하지 않으면 해당 문서에 대해 이름 비교가 수행되지 않습니다. `text` 필드만 성명 필드가 될 수 있습니다. |

예시:

```json theme={null}
{
  "feature": "DOCUMENT_AI",
  "config": {
    "document_ai_documents": [
      {
        "document_key": "proof_of_funds",
        "title": "Proof of Funds",
        "description": "Upload a recent bank statement.",
        "title_i18n": { "es": "Comprobante de fondos" },
        "fields": [
          {
            "key": "account_holder",
            "name": "Account holder",
            "instruction": "The full name of the account holder as printed on the statement.",
            "type": "text",
            "required": true,
            "is_full_name": true
          },
          {
            "key": "closing_balance",
            "name": "Closing balance",
            "instruction": "The closing balance amount.",
            "type": "number",
            "required": false
          }
        ]
      }
    ],
    "document_ai_missing_required_fields_action": "REVIEW",
    "document_ai_name_mismatch_action": "REVIEW",
    "document_ai_name_match_score_threshold": 80
  }
}
```

## 전자 서명

기능 값: `SIGNATURE`.

인증된 사람 또는 회사의 주요 인물이 문서에 서명하도록 합니다. 수준은 Simple(기본값) 또는 고급(AES)입니다. 서명자를 검증하는 단계 뒤에 배치하세요: 신분증 인증, 그리고 코드 확인을 위한 이메일 인증 또는 전화번호 인증. 자세한 내용은 [전자 서명](https://docs.didit.me/ko/core-technology/electronic-signature/overview.md)을 참조하세요.

| 구성 필드 | 유형 | 설명 |
| - | - | - |
| `signature_documents` | array | 콘솔에서 이 워크플로에 업로드된 문서로, 서명자가 보는 순서대로 `[{"uuid", "title", "file_name", "pages", "size_bytes"}]` 형식입니다. `uuid` 값과 그 순서만 읽으며, 나머지 정보는 저장된 파일에서 가져옵니다. 문서는 최대 20개, 전체 50 MB까지입니다. 기본값 `[]`. |
| `signature_documents_source` | string | 문서의 출처: `workflow`(기본값), `session`([세션 생성](https://docs.didit.me/ko/sessions-api/create-session.md#전자-서명-문서)의 `sign.documents`) 또는 `both`(워크플로 문서가 먼저). |
| `signature_require_read_to_end` | boolean | 서명자는 필드가 없는 각 문서의 끝까지 읽어야 동의할 수 있습니다. 기본값 `true`. |
| `signature_consent_per_document` | boolean | 서명자는 필드가 없는 각 문서에 개별적으로 동의합니다. 필드가 있는 문서에서는 안내된 필드와 최종 동의가 이를 대신합니다. 기본값 `true`. |
| `signature_signer` | string | 서명자: `verified_person`(기본값, KYC), 또는 KYB의 경우 `legal_representative`(역할이 `representative` 또는 `authorized_signatory`인 주요 인물) 또는 `key_people`(KYC 세션이 있는 모든 개인 주요 인물). |
| `signature_level` | string | `simple`(기본값): 신분증 인증, 이메일, 전화번호 또는 코드가 필요하지 않으며, 서명자가 이름을 입력하고 세션 링크에서 서명합니다. `aes`: 승인된 신분증 인증, 인증된 이메일 또는 전화번호, 일회용 코드가 필요합니다. `legal_representative` 및 `key_people` 서명자의 경우 `simple`은 `signature_simple_requires_verified_person`으로 거부됩니다. 워크플로에서 `signature_availability.aes`가 `false`인 동안 새 `aes` 단계를 저장하면 `aes_not_available`과 함께 `400`이 반환됩니다. `qes`는 곧 제공될 예정입니다. 이를 저장하면 `qes_not_available`과 함께 `400`이 반환됩니다. |
| `signature_format` | string | `pades`(기본값). AES에서 `xades`와 `cades`는 `signature_format_not_supported`로 거부됩니다. |
| `signature_otp_channel` | string | 일회용 코드를 보낼 위치: `email`(기본값) 또는 `sms`. 세션에서 앞서 인증된 연락처로만 전송됩니다. |
| `signature_email_signed_copy` | boolean | 서명자에게 서명된 문서 사본을 이메일로 보냅니다. 인증된 이메일이 필요합니다. 기본값 `true`. |
| `signature_evidence_page` | boolean | 서명된 각 PDF 끝에 증거 페이지를 추가합니다. 기본값 `true`. |
| `signature_link_validity_days` | integer | 서명 링크가 세션 생성 후 며칠 동안 유효한지 설정합니다. `1`에서 `30`일 사이입니다. 기본값 `7`. |
| `signature_declined_action` | action | 서명자가 서명을 거부할 때의 판정입니다. 요금은 청구되지 않습니다. 기본값 `REVIEW`. |
| `signature_otp_failed_action` | action | 잘못된 코드를 3회 이상 입력하거나 5회를 초과하여 코드를 요청한 후의 판정입니다. 기본값 `DECLINE`. |
| `signature_name_mismatch_action` | action | 주요 인물이 선언한 이름이 인증된 이름과 일치하지 않을 때의 판정입니다. 기본값 `DECLINE`. |
| `signature_identity_not_verified_action` | action | 서명자에게 승인된 신원 증거가 없을 때의 판정입니다. 기본값 `DECLINE`. |
| `signature_document_changed_action` | action | 문서가 표시될 때 기록된 SHA-256과 더 이상 일치하지 않을 때의 판정입니다. 기본값 `DECLINE`. |
| `status_rules` | array | 선택 사항인 사용자 지정 상태 규칙입니다. `signature.status`, `signature.level`, `signature.format`을 대상으로 지정할 수 있습니다. |

워크플로 문서의 필드는 콘솔의 템플릿 편집기에 배치됩니다. 세션 문서의 경우 `sign.documents[].fields`로 보내고, `api.<key>` 필드의 값은 `sign.field_values`로 보냅니다. [세션 생성](https://docs.didit.me/ko/sessions-api/create-session.md#전자-서명-문서)을 참조하세요.

예시, 각 세션과 함께 보내는 문서의 경우:

```json theme={null}
{
  "feature": "SIGNATURE",
  "config": {
    "signature_documents_source": "session",
    "signature_signer": "verified_person",
    "signature_level": "aes",
    "signature_otp_channel": "email",
    "signature_link_validity_days": 14,
    "signature_declined_action": "REVIEW"
  }
}
```


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