생체 인증 보고서: JSON 스키마

생체 인증 보고서는 Didit이 재방문 사용자의 재인증 결과를 보고하는 방식입니다. 워크플로는 새로운 라이브니스 검사를 실행하며, 워크플로에서 얼굴 대조가 활성화된 경우 세션 생성 시 결정된 기준 얼굴(직접 제공한 portrait_image 또는 vendor_data로 조회한 사용자의 저장된 얼굴)과 1:1 얼굴 대조를 수행합니다. 두 검사는 모두 V3 세션 결정 응답에서 표준 기능 항목으로 표시됩니다.

저장된 인물 사진과 라이브니스 검사 및 얼굴 대조를 결합한 Didit 생체 인증 보고서

개요

생체 인증은 별도의 응답 객체가 아닌 워크플로 유형(workflow_type: "biometric_authentication")입니다. 워크플로가 실행되면 다음이 생성됩니다:

라이브 셀피를 캡처하고 스푸핑 여부를 점수화하는 라이브니스 검사 1건.
캡처된 얼굴을 세션 생성 시 결정된 기준 얼굴과 비교하는 얼굴 대조 1건(워크플로에서 얼굴 대조가 활성화된 경우에만 해당).

워크플로에 얼굴 대조가 포함된 경우 세션 생성 시 기준 얼굴이 필요합니다. portrait_image(base64로 인코딩된 이미지, 최대 2MB)를 전송하거나, 이를 생략하면 Didit이 vendor_data 사용자에 대해 이미 저장된 얼굴(승인된 라이브니스 얼굴 우선, 그 다음 전자여권(ePassport) 칩 사진, 신분증 문서 인물 사진, 수동 등록된 프로필 얼굴 순)을 재사용합니다. portrait_image와 저장된 얼굴을 모두 사용할 수 없는 경우 세션 생성 시

{"portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first."}

와 함께 400이 반환됩니다. 두 경우 모두 확인된 기준 얼굴이 새 세션 아래에 기록되므로, 얼굴 대조 항목의 source_image_session_id는 해당 세션 자체의 session_id로 설정됩니다(동일 세션에서 캡처되어 해당 필드가 null로 유지되는 신분증 문서 인물 사진이 아니라, 세션에 저장된 인물 사진에서 기준 얼굴을 가져왔음을 나타냄).

표시 위치

결정 응답 키	복수 여부	항목 스키마
`liveness_checks[]`	라이브니스 단계당 1개(생체 인증에서는 보통 1개)	data-models#liveness-check
`face_matches[]`	얼굴 대조 단계당 1개(라이브니스 전용 워크플로에서는 `null`)	data-models#face-match

두 배열 모두 워크플로 유형이 biometric_authentication인 세션에 대해 GET /v3/session/{sessionId}/decision/에서 반환됩니다. 이들은 단일 객체가 아닌 항상 배열이며, 각 단계에서 데이터가 생성될 때까지 null 상태를 유지합니다. 다중 인스턴스 워크플로에서 단계를 명확히 구분할 수 있도록 각 항목에는 node_id가 포함됩니다.

스키마 참조

전체 필드 목록은 데이터 모델 페이지에 한 번 정의되어 있으므로 이러한 기능을 표시하는 모든 보고서가 단일 정보 소스를 공유합니다:

라이브니스 항목 스키마 — status, method, score, reference_image, video_url, age_estimation, matches[], face_quality, face_luminance, warnings[], node_id.
얼굴 대조 항목 스키마 — status, score, source_image_session_id, source_image, target_image, warnings[], node_id.
경고 항목 구조 — feature, risk, additional_data, log_type, short_description, long_description, node_id.

상태 값

liveness_checks[].status와 face_matches[].status는 모두 공통 기능 수명 주기(기능 수준 상태)를 사용합니다:

상태	의미
`Not Finished`	해당 단계가 아직 최종 결과를 생성하지 않았습니다(사용자가 완료하지 않았거나 이탈함). 단계가 시작되기 전에는 결정 응답에서 해당 배열이 단순히 `null`로 표시됩니다.
`Approved`	검사가 설정된 모든 임계값을 통과했습니다.
`In Review`	점수가 검토 구간에 속하거나, 설정 가능한 경고가 검토로 설정되었습니다.
`Declined`	점수가 거부 임계값 이하로 떨어졌거나 자동 거부 경고가 발생했습니다(얼굴 공격, 얼굴 감지되지 않음, 차단 목록에 등록된 얼굴, 얼굴 대조용 기준 이미지 없음).
`Resub Requested`	검토자가 사용자에게 이 단계를 재시도하도록 요청했습니다.

전체 세션 status는 두 항목을 종합하여 결정됩니다. 어느 기능이든 Declined 상태이면 세션이 거부되고, In Review 상태이면 세션이 In Review 상태가 되며, 그렇지 않으면(모든 기능이 완료된 후) Approved 상태가 됩니다. 임계값 동작 및 경고 코드의 전체 목록은 생체 인증 경고를 참조하십시오.

예시 — 라이브니스 + 얼굴 대조 (승인됨)

예시는 축약되어 있습니다. 전체 결정 응답에는 session_url, metadata, callback, reviews, contact_details, expected_details, environment, created_at, expires_at도 포함됩니다.

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_kind": "user",
  "session_number": 1234,
  "status": "Approved",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "features": ["LIVENESS", "FACE_MATCH"],
  "vendor_data": "user-123",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 89.92,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 92.4,
      "face_luminance": 58.1,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Approved",
      "score": 88.47,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": []
    }
  ],
  "id_verifications": null,
  "nfc_verifications": null,
  "poa_verifications": null,
  "phone_verifications": null,
  "email_verifications": null,
  "aml_screenings": null
}

예시 — 라이브니스 전용 (워크플로에서 얼굴 대조 비활성화됨)

{
  "session_id": "22222222-3333-4444-5555-666666666666",
  "session_kind": "user",
  "status": "Approved",
  "workflow_id": "018e7b2c-6666-7777-9999-bbbbbbbbbbbb",
  "features": ["LIVENESS"],
  "vendor_data": "user-456",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "ACTIVE_3D",
      "score": 96.10,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": null,
      "face_luminance": null,
      "warnings": []
    }
  ],
  "face_matches": null
}

라이브니스 전용 모드는 워크플로 구성 방식 중 하나입니다. 얼굴 대조가 비활성화된 경우 세션 생성 시 기준 얼굴이 필요하지 않으며 face_matches는 null 상태를 유지합니다. 얼굴 대조가 활성화되어 있는 경우, portrait_image를 생략하더라도 라이브니스 전용으로 대체되지 않고 Didit이 vendor_data 사용자에 대해 저장된 얼굴을 재사용하며, 저장된 얼굴이 없으면 세션 생성이 400 오류로 실패합니다.

예시 — 낮은 유사도로 인한 얼굴 대조 거부

{
  "session_id": "33333333-4444-5555-6666-777777777777",
  "status": "Declined",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 91.20,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 90.15,
      "face_luminance": 55.30,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Declined",
      "score": 41.18,
      "source_image_session_id": "33333333-4444-5555-6666-777777777777",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "error",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match"
        }
      ]
    }
  ]
}

보안 참고 사항

reference_image, video_url, source_image, target_image는 유효 기간(기본값 4시간)이 지나면 만료되는 서명된 URL입니다. 이 URL들은 생체 인식 데이터를 가리키므로 캐시하거나 공개적으로 노출하지 마십시오. 인증 결과(status, score, source_image_session_id)는 사용자 측에 저장하고, 새로운 URL이 필요한 경우 결정 endpoint를 다시 호출하십시오.

생체 인증 경고

경고 코드, 임계값 및 자동 거부 조건.

라이브니스 보고서

liveness_checks[] 항목에 대한 전체 필드 참조.

얼굴 대조 보고서

face_matches[] 항목에 대한 전체 필드 참조.

인증

인증

모니터링

플랫폼

생체 인증 보고서: JSON 스키마

개요

표시 위치

스키마 참조

상태 값

예시 — 라이브니스 + 얼굴 대조 (승인됨)

예시 — 라이브니스 전용 (워크플로에서 얼굴 대조 비활성화됨)

예시 — 낮은 유사도로 인한 얼굴 대조 거부

보안 참고 사항

관련 항목

생체 인증 경고

라이브니스 보고서

얼굴 대조 보고서

​개요

​표시 위치

​스키마 참조

​상태 값

​예시 — 라이브니스 + 얼굴 대조 (승인됨)

​예시 — 라이브니스 전용 (워크플로에서 얼굴 대조 비활성화됨)

​예시 — 낮은 유사도로 인한 얼굴 대조 거부

​보안 참고 사항

​관련 항목

생체 인증 경고

라이브니스 보고서

얼굴 대조 보고서

개요

표시 위치

스키마 참조

상태 값

예시 — 라이브니스 + 얼굴 대조 (승인됨)

예시 — 라이브니스 전용 (워크플로에서 얼굴 대조 비활성화됨)

예시 — 낮은 유사도로 인한 얼굴 대조 거부

보안 참고 사항

관련 항목