메인 콘텐츠로 건너뛰기
PATCH
curl

KYC 및 KYB 지원

이 endpoint는 사용자 인증(KYC) 세션과 기업 확인(KYB) 세션에 동일하게 작동합니다. Didit은 두 세션 유형 모두에 대해 session_id를 확인하며, 상태 전환 검증은 두 유형에 동일하게 적용됩니다(두 유형에 같은 상태 열거형이 적용됩니다). 응답에는 session_id만 포함됩니다. 다운스트림 로직에서 세션 유형에 따라 분기해야 할 경우 세션 조회에서 session_kind를 읽으세요.

허용되는 상태 전환

세션을 Approved, Declined, 또는 Resubmitted로 변경할 수 있습니다. 그 외의 new_status 값(In Review 포함)은 400을 반환합니다. 세션의 현재 상태는 Approved, Declined, In Review, Kyc Expired, Abandoned, Resubmitted 중 하나여야 합니다. 그렇지 않으면 API가 400을 반환합니다. 세션이 이미 해당 상태일 때 Approved 또는 Declined를 설정하면 아무 작업도 일어나지 않습니다. API는 200을 반환하며 아무것도 변경하지 않고, webhook도 발송하지 않고, 이메일도 보내지 않습니다. 이미 Resubmitted 상태인 세션에 Resubmitted를 설정하면 400(The new status is the same as the current status.)을 반환합니다. nodes_to_resubmit에 백엔드 전용 기능(AML, DATABASE_VALIDATION, IP_ANALYSIS)만 포함된 재제출은 자동으로 실행되며, 사용자 상호작용 없이 세션을 결정된 상태로 되돌립니다. 이러한 재제출을 30초 이내에 반복하면 Retry-After 헤더와 함께 429 Too Many Requests를 반환합니다. 즉시 반복해도 다른 결과가 나올 수 없기 때문입니다. In Review 상태를 받을 때마다 webhook 핸들러에서 자동으로 재제출하지 마세요. 먼저 결과를 검토하거나 기반 데이터를 변경하세요.

먼저 이메일 미리보기

send_email: true를 설정하면 Approved와 Declined는 해당 사용자에게 결정 이메일을 보내고, Resubmitted는 사유와 함께 새 링크를 보냅니다. 무엇이든 변경하기 전에 이 이메일을 미리 확인할 수 있습니다.
  1. Approved 또는 Declined에는 결정 이메일 미리보기를, Resubmitted에는 재제출 이메일 미리보기를 호출하세요.
  2. 렌더링된 subject와 html, recipient, 그리고 will_be_sent / not_sent_reason을 확인하세요.
  3. 동일한 new_status(재제출인 경우 동일한 nodes_to_resubmit도 함께), send_email: true, recipient 값으로 설정한 email_address, 미리 본 email_language, 그리고 preview_token 값으로 설정한 email_preview_token을 사용해 이 endpoint를 호출하세요.
두 미리보기 모두 세션을 변경하지 않으며 아무것도 보내지 않습니다. 업데이트는 미리 본 이메일과 정확히 같은 이메일만 보냅니다. 영수증은 15분 후에 만료됩니다. 미리보기 이후 수신자, 언어, 세션 상태, 발신자 또는 이메일이 변경되었다면, 아무것도 바뀌기 전에 업데이트가 409를 반환합니다. 이 경우 다시 미리보기를 하고 새 영수증으로 확인하세요. send_email: true 없이 email_preview_token을 보내면 400을 반환합니다. 미리보기 단계는 선택 사항입니다. 기존 연동은 이 단계 없이 계속 이 endpoint를 호출할 수 있습니다.

예제

권한

write:sessions 권한이 필요합니다. 같은 권한이 두 유형 모두에 적용됩니다.

관련 문서

인증

x-api-key
string
header
필수

Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본 키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며 특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나 만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된 IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를 벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write 권한이 없는 키는 세션 링크와 token을 null로 수신합니다. https://docs.didit.me/console/api-keys 를 참고하십시오.

경로 매개변수

sessionId
string<uuid>
필수

업데이트할 인증 세션의 UUID입니다. 사용자(KYC) 및 기업(KYB) 세션 ID를 모두 지원하며, 서비스는 두 세션 유형 전체에서 ID를 확인합니다.

예시:

"11111111-2222-3333-4444-555555555555"

본문

application/json
new_status
enum<string>
필수

대상 상태입니다. Approved 및 Declined는 최종 수동 결정을 기록합니다(서로를 번복할 수도 있음). Resubmitted는 선택한 단계를 지우고 세션을 사용자에게 다시 보냅니다. 다른 값은 400을 반환합니다.

사용 가능한 옵션:
Approved,
Declined,
Resubmitted
예시:

"Approved"

comment
string

변경에 대한 자유 형식 사유로, 세션의 검토 기록에 저장되며 Get Decision의 reviews 배열로 반환됩니다. 예: Duplicated user.

예시:

"All checks passed manual review"

nodes_to_resubmit
object[]

사용자가 다시 진행해야 하는 워크플로 단계입니다. new_status가 Resubmitted인 경우에만 처리됩니다. Approved/Declined의 경우 항목에 대한 스키마 유효성 검사는 계속 수행되지만(유효하지 않은 feature 값은 400 반환), 유효한 항목은 의미론적으로 무시됩니다. 생략할 경우, 서버는 상태가 Declined, In Review, Not Finished 또는 Expired인 기존 OCR, Liveness, Face Match, POA, Phone, Email, AML, Database Validation, Questionnaire 시도를 자동으로 선택합니다(NFC, IP 분석, 연령 추정, 얼굴 검색 및 KYB 문서 시도는 절대 자동 선택되지 않으며, 얼굴 대조가 아닌 얼굴 시도는 LIVENESS로 선택됨). 사용자가 시도한 적 없는 기능(기록된 시도 없음)은 선택되지 않으므로 시도가 0건인 세션은 승인된 항목이 없더라도 400("No features found that need resubmission")을 반환합니다. 이 경우에는 nodes_to_resubmit을 명시적으로 전달하십시오. 단계는 전송 순서와 관계없이 워크플로 그래프 순서대로 실행됩니다. KYB_REGISTRY, KYB_KEY_PEOPLE 및 KYB 별칭은 400으로 거부됩니다. 이러한 상위 검사는 하위 KYC 세션에서 다시 계산됩니다.

send_email
boolean
기본값:false

사용자에게 변경 사항에 대한 이메일을 보낼지 여부입니다. email_address가 필요합니다. Approved/Declined의 경우 사용자는 상태 알림을 받으며, Resubmitted의 경우 이메일에 인증 링크와 단계별 재제출 사유가 포함됩니다.

예시:

false

email_address
string<email>

알림 이메일을 수신할 수취인입니다. send_email이 true일 때 필수이며, 생략 시 400이 반환됩니다.

예시:

"user@example.com"

email_language
string
기본값:en

알림 이메일 언어입니다. 스키마 수준에서 모든 문자열을 허용하며, 지원되지 않는 코드는 영어(en)로 자동 대체됩니다.

예시:

"en"

email_preview_token
string
write-only

Preview Decision Email(Approved 및 Declined용) 또는 Preview Resubmission Email(Resubmitted용)의 선택적 영수증인 preview_token입니다. send_email: true일 때만 유효하며, 그렇지 않으면 요청이 400을 반환합니다. 수신자, 언어, 세션 상태, 발신자 및 이메일(재제출의 경우 선택한 단계 포함)이 미리보기와 계속 일치해야 하며, 영수증은 15분 후에 만료됩니다. 그렇지 않으면 세션이 변경되거나 이메일이 전송되기 전에 요청이 409를 반환합니다. 기존 연동에서는 이 필드를 생략할 수 있습니다.

Required string length: 1 - 512

응답

상태가 업데이트되었습니다. 응답에는 session_id만 포함됩니다. 업데이트된 세션은 결정 조회를 통해 가져오십시오. 변경 사항이 커밋되면 status.updated webhook이 트리거됩니다. Approved 또는 Declined를 반복 호출하면 동일한 본문이 반환되고 아무것도 변경되지 않습니다.

session_id
string<uuid>

업데이트된 세션의 UUID입니다.

마지막 수정일 2026년 11월 7일