메인 콘텐츠로 건너뛰기
POST
cURL

KYC 및 KYB 지원

하나의 endpoint로 사용자 인증(KYC) 세션과 기업 확인(KYB) 세션을 모두 생성합니다. 워크플로의 유형에 따라 생성되는 세션의 종류가 결정됩니다.
  • KYC 워크플로의 workflow_id를 전달하면 사용자 인증(KYC) 세션이 생성됩니다. 응답에는 session_kind: "user"가 포함됩니다.
  • KYB 워크플로의 workflow_id를 전달하면 기업 확인(KYB) 세션이 생성됩니다. 응답에는 session_kind: "business"가 포함됩니다.
워크플로는 Workflows → Create workflow에서 콘솔을 통해 구성합니다. 워크플로는 생성 시점에 KYC 또는 KYB 중 하나로 정해지며, 이후에는 유형을 바꿀 수 없습니다.

예제

응답 (201 Created):

전자 서명 문서

워크플로에 세션의 문서를 사용하는 전자 서명 단계가 있으면(signature_documents_source가 session 또는 both로 설정된 경우) 해당 문서를 sign.documents에 담아 보냅니다. 각 문서는 base64로 인코딩한 파일이므로, Didit이 URL에서 파일을 가져올 필요가 없습니다.
fields를 생략하면 서명자는 문서를 읽고 동의합니다.

앵커 텍스트로 필드 배치

위치 대신 필드에 anchor를 지정할 수 있습니다. 앵커는 필드가 놓일 위치를 표시하는 문서 내 텍스트입니다. 세션마다 생성하는 문서, 예를 들어 Word 템플릿으로 만든 문서에 적합합니다. 워크플로 문서의 경우에는 콘솔에서 필드를 배치하세요. 문서에 앵커 텍스트가 없으면 호출은 400과 함께 field_anchor_not_found, 그리고 해당 필드의 키를 반환합니다. Didit은 PDF에서 앵커 텍스트를 제거하지 않으므로, 페이지 배경과 같은 색으로 작성하세요.

필드 값

sign.field_values는 워크플로 문서와 세션 문서 모두에서 prefill이 api.<key>인 모든 필드의 값을 설정합니다. 객체이며, 키는 이러한 <key> 이름입니다. 값은 text 및 data 필드의 경우 1~500자의 문자열이고, checkbox 필드의 경우 불리언입니다.

오류 및 반복 호출

세션은 문서를 최대 20개, 총 50MB까지 받을 수 있습니다. 다음의 경우 호출은 sign 오류와 함께 400을 반환합니다.
  • 워크플로에 전자 서명 단계가 없는 경우
  • sign.documents를 보냈는데 해당 단계가 워크플로 문서만 받는 경우
  • 단계가 세션 문서만 받는데 세션 문서를 보내지 않았거나, 워크플로 문서가 없는데 세션 문서도 보내지 않은 경우
  • 문서가 너무 크거나, 올바른 base64가 아니거나, 지원되지 않는 파일인 경우
  • Word 파일이 signature_document_not_supported로 거부되었거나 변환할 수 없어 signature_document_conversion_failed를 반환하는 경우. 각 오류의 reason은 지원 파일에 나열되어 있습니다.
  • 필드가 잘못되었거나, 앵커를 찾을 수 없거나(field_anchor_not_found), 필드 값이 거부된 경우
같은 workflow_id와 vendor_data로 생성을 다시 호출하면 대기 중인 세션이 반환됩니다. 그 호출에 sign이 포함되어 있다면, 문서, 필드, 필드 값은 첫 번째 호출과 완전히 같아야 합니다(순서, 제목, 파일 이름, 내용, 필드, 값 모두 동일해야 합니다). 하나라도 다르면 {"sign": "signature_document_changed"}와 함께 400이 반환됩니다. 이 경우 다른 vendor_data를 사용하거나, 대기 중인 세션이 끝날 때까지 기다리세요.

샌드박스 시나리오로 테스트

샌드박스 모드 애플리케이션에서 sandbox_scenario를 전달하면, 실제 제공자나 잔액을 사용하지 않고 결정된 결과(승인, 특정 거부, 또는 검토 중 시나리오)를 미리 설정할 수 있습니다.
sandbox_scenario는 라이브 애플리케이션에서 400으로 거부됩니다. 세션을 생성하는 시점에 결과를 아직 모른다면, 세션이 여전히 Not Started 상태일 때 나중에 POST /v3/session/{session_id}/sandbox/arm/로 시나리오를 설정(또는 다시 설정)할 수 있습니다. 호스티드 흐름의 사전 시나리오 선택기도 이 엔드포인트를 사용합니다. 전체 시나리오 목록, 매직 값 레지스트리, arm endpoint의 요청 및 응답 형식은 샌드박스 및 테스트 데이터에서 확인하세요.

vendor_data는 세션을 엔티티에 연결합니다

  • KYC 워크플로의 경우 사용자 엔티티에 연결됩니다. 사용자가 없으면 자동으로 생성됩니다.
  • KYB 워크플로의 경우 기업 엔티티에 연결됩니다. 새로운 기업이면 자동으로 생성됩니다.
자세한 내용은 vendor data 연결에서 확인하세요.

일리노이주, 텍사스주 및 콜로라도주의 생체 인식 동의

호스티드 흐름과 네이티브 SDK 4.10.0 이상은 애플리케이션의 동의 모드와 사용자가 있는 위치에 따라, 첫 얼굴 촬영 전에 명시적인 생체 인식 동의 단계를 표시할 수 있습니다. 이 판단에는 두 개의 선택적 필드가 사용됩니다.
  • user_state: 알고 있는 경우 사용자가 거주하는 지역입니다(US-IL, IL 또는 Illinois). 자동 모드에서는 해당 주가 적용 대상이면 흐름이 동의를 요청합니다.
  • biometric_consent: 이미 수집한 동의를 위한 객체이며, given_at과 text_version을 포함합니다. 흐름은 동의를 다시 요청하지 않습니다.
4.10.0 미만의 네이티브 SDK에서는 이 단계를 표시할 수 없습니다. 이러한 세션은 기존과 같이 실행되며, 판단 결과에는 동의가 수집되지 않은 것으로 보고됩니다. 자세한 내용은 생체 인식 동의를 참조하십시오.

중요: 고지와 동의는 귀사의 제품에서 이루어집니다

Create Session은 인증 URL과 세션 토큰을 생성합니다. 그 자체만으로는 사용자에게 고지 사항을 제공했다거나 특정 사용 사례에 필요한 동의를 받았다는 사실을 증명하지 않습니다. 귀사의 애플리케이션, 웹사이트, SDK 래퍼 또는 화이트 라벨 흐름에서 Didit 세션을 시작하는 경우, 사용자가 촬영을 시작하기 전에 법적 사항은 귀사의 UX에서 직접 처리해야 합니다.

사전 인증 체크리스트 권장 항목

  1. 이 인증을 귀사가 요청하고 있으며, 이 흐름을 제공하는 인증 제공업체이자 처리자가 Didit임을 사용자에게 알리십시오.
  2. 귀사의 개인정보 처리방침과 이 과정에 적용되는 컨트롤러 측 법적 약관에 링크하십시오.
  3. Didit의 인증 개인정보 처리방침과 신원 인증을 위한 최종 사용자 약관에 링크하십시오.
  4. 문서 촬영, 셀피 촬영, 라이브니스 또는 생체 인식이 워크플로에 포함되는 경우, 관련 법률이나 귀사의 법적 입장에서 요구하는 경우에는 명시적인 적극적 동의를 받으십시오.
  5. 사용자 지정 UI, 사용자 지정 도메인 또는 API 전용 과정을 사용하는 경우, 사용자를 Didit 흐름으로 보내기 전에 귀사의 제품에 이러한 고지 사항을 표시하십시오.
  6. 법무팀이 감사 추적을 요구하는 경우, 고지 및 동의 문구, 타임스탬프와 관련 메타데이터를 귀사의 기록으로 보관하십시오.
법적 요건은 관할 지역마다 다릅니다. 화이트 라벨 브랜딩이 있다고 해서 인증 흐름에서 Didit의 역할이 사라지지는 않습니다. 생체 인식 관련 특별 규정이 있는 관할 지역에서 운영하는 경우, 출시 전에 법률 전문가와 함께 구현을 검토하십시오.

인증

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 를 참고하십시오.

본문

application/json
workflow_id
string<uuid>
필수

세션에서 실행할 인증 단계를 정의하는 워크플로의 안정적인 식별자입니다. 워크플로는 콘솔의 워크플로 페이지에서 생성 및 관리됩니다. workflow_id는 세션이 KYC인지 KYB인지도 암시적으로 선택합니다.

예시:

"11111111-2222-3333-4444-555555555555"

vendor_data
string

인증 대상 사용자의 고유 식별자(UUID, 이메일, 내부 사용자 ID 등)입니다. 이 필드는 다음 용도로 사용됩니다. (1) 사용자 그룹화 — 동일한 vendor_data를 가진 세션은 Users 탭에서 동일한 사용자 프로필로 연결됩니다. (2) 세션 간 중복 감지 — 중복된 얼굴, 문서, 전화번호, 이메일, IP 주소 또는 기기 지문을 확인할 때 동일한 vendor_data를 가진 세션은 동일한 사용자로 처리되어 일치 항목에서 제외됩니다. vendor_data가 없으면 모든 세션이 고유한 사용자로 처리되어 모든 잠재적 중복 항목이 표시됩니다. 중복 감지의 노이즈를 줄이기 위해 항상 vendor_data를 제공하는 것을 강력히 권장합니다.

예시:

"user-123"

multi_account_segment
string

조직 내의 선택적 중복 감지 영역입니다. 중복 얼굴 확인은 이 세션을 동일한 세그먼트를 가진 다른 세션들과만 비교하므로, 별도의 계정 기반(개인 및 기업 계정 또는 B2B 하위 고객사별 계정)이 있는 경우 양쪽에 정당하게 계정을 보유한 인물을 오탐 플래그로 지정하지 않습니다. 생략하면 현재 모든 세션이 사용하는 단일 기본 영역을 사용합니다. 차단 목록 및 허용 목록 매칭 시에는 이 필드가 무시됩니다.

Maximum string length: 64
예시:

"business-accounts"

callback
string

인증 완료 후 사용자를 리디렉션할 URL입니다. Didit은 verificationSessionId 및 status(Approved, Declined, In Review)를 쿼리 파라미터로 자동 추가합니다. 모바일 콜백을 위한 커스텀 URL 스킴(예: myapp://)이 지원됩니다. 생략하면 워크플로의 기본 callback_url이 사용됩니다. 애플리케이션에 허용된 도메인이 설정된 경우(PATCH /v3/webhook/의 allowed_domains), http 또는 https 콜백은 해당 오리진 중 하나에 있어야 하며(동일한 스킴, 호스트 및 포트), 그렇지 않으면 callback에서 400 오류와 함께 요청이 실패합니다: callback must be on one of the application's allowed domains: https://app.example.com. 커스텀 URL 스킴은 항상 허용됩니다.

예시:

"https://example.com/verification/callback"

callback_method
enum<string>
기본값:initiator

제공된 콜백 URL로의 리디렉션을 처리할 기기를 결정합니다. 흐름을 시작한 기기만 리디렉션하려면 initiator, 흐름을 완료하는 기기는 completer, 두 기기 중 어느 쪽이든 콜백을 트리거할 수 있도록 허용하려면 both를 사용하십시오. 콜백이 안정적으로 트리거되지 않는 문제가 발생할 경우 이 값을 both로 설정하는 것을 권장합니다.

사용 가능한 옵션:
initiator,
completer,
both
예시:

"both"

metadata
any

세션과 함께 저장되며 응답 및 webhook에 그대로 반환되는 임의의 JSON입니다. 모든 JSON 값(객체, 문자열, 숫자, 배열)이 허용되지만, 키/값 쌍의 JSON 객체를 사용하는 것이 좋습니다. 최종 사용자에게는 표시되지 않습니다. 자체 상관 관계 ID, A/B 변형 또는 비즈니스 컨텍스트를 전달하는 데 사용하십시오.

예시:
tags
string[]

세션이 생성될 때 이름별로 추가된 태그입니다. 최대 10개, 각각 최대 50자입니다. 이름은 대소문자를 구분하지 않으며 대문자로 저장됩니다. 애플리케이션에 아직 존재하지 않는 이름은 새 태그로 생성됩니다. 태그는 콘솔의 세션에 표시되며, 이를 기준으로 필터링할 수 있습니다.

Maximum array length: 10
Maximum string length: 50
예시:
language
enum<string>

인증 프로세스 인터페이스의 언어 코드(ISO 639-1)입니다. 인증 중에 최종 사용자에게 표시되는 언어를 제어합니다. 제공되지 않으면 브라우저 언어가 자동으로 감지되어 사용됩니다. 지원되는 모든 언어는 여기에서 확인하세요.

사용 가능한 옵션:
en,
ar,
bg,
bn,
bs,
ca,
cnr,
cs,
da,
de,
el,
es,
et,
fa,
fi,
fr,
he,
hi,
hr,
hu,
hy,
id,
it,
ja,
ka,
kk,
ko,
ky,
lt,
lv,
mk,
mn,
ms,
nl,
no,
pl,
pt-BR,
pt,
ro,
ru,
sk,
sl,
so,
sq,
sr,
sv,
th,
tr,
uk,
uz,
vi,
zh-CN,
zh-TW,
zh
예시:

"en"

contact_details
object

알림, 인증 양식 자동 완성 및 전화번호 인증에 사용할 수 있는 사용자 연락처 정보입니다. 이메일 주소, 통신에 사용할 선호 언어 및 전화번호가 포함됩니다.

예시:
expected_details
object

사용자의 신분증 문서, 주소 증명 및 기타 인증 단계에서 추출된 데이터와 교차 검증하는 데 사용되는 예상 사용자 세부정보입니다. 불일치 항목은 결정 시 경고로 표시되며, 일부 필드(예: id_country, expected_document_types)는 사용자 대상 플로우를 변경하기도 합니다. 기업 확인(KYB) 워크플로의 경우 기업 필드(company_name, registry_country, registration_number)만 사용되어 사용자를 위한 법인 등기부 검색을 미리 채우며, 모든 개인 단위 필드는 무시됩니다.

예시:
portrait_image
string<byte>

최종 사용자의 얼굴을 촬영한 Base64 인코딩된 인물 사진 이미지입니다(최대 2MB, JPEG, PNG, WebP 또는 TIFF). 워크플로가 얼굴 대조가 활성화된 Biometric Authentication 워크플로이거나, 얼굴 대조가 신분증 인증(OCR)보다 먼저 실행되는 그래프 워크플로인 경우 라이브니스 캡처와 대조할 기준 이미지로 사용됩니다. vendor_data 사용자에게 이미 저장된 얼굴 이미지가 있는 경우 선택 사항입니다. Didit은 승인된 라이브니스 얼굴, 전자여권(ePassport) 칩 사진, 신분증 인물 사진, 직접 등록한 프로필 얼굴 순으로 우선순위를 확인하여 자동으로 재사용합니다(승인된 세션의 얼굴 또는 직접 등록한 얼굴만 재사용됨). portrait_image가 제공되면 저장된 얼굴보다 항상 우선 적용됩니다. 생략되었고 저장된 얼굴도 없는 경우(또는 vendor_data가 전송되지 않은 경우) 세션 생성은 400 오류로 실패합니다. 다른 워크플로 유형에서는 무시됩니다.

예시:

"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="

sandbox_scenario
string

샌드박스 전용 시나리오 slug입니다. API 키가 샌드박스 모드 애플리케이션에 속한 경우에만 허용되며, 프로덕션 애플리케이션에서는 거부됩니다. 설정 시 생성 흐름에서 시나리오에 번들된 매직 값을 세션의 입력 필드(contact_details, expected_details)로 확장하여 모의 제공업체가 실제 워크플로 파이프라인을 통해 시나리오 결과를 재현하도록 합니다. GET /v1/sandbox/scenarios/ 또는 Sandbox & Test Data에서 시나리오 카탈로그를 확인하세요. 또한 세션이 아직 Not Started 상태인 경우 POST /v3/session/{sessionId}/sandbox/arm/을 통해 생성 후 시나리오를 준비(또는 재준비)할 수도 있습니다. 비문서 조회의 경우 lookup_partial_match, lookup_no_match 또는 lookup_provider_error를 사용하여 구성된 시도 예산 및 폴백을 테스트하세요. 신원 지갑의 경우 wallet_cancelled, wallet_timeout 또는 wallet_provider_error를 사용하세요. approve는 검증된 지갑을 시뮬레이션합니다. 프로덕션 애플리케이션에서 사용할 수 없는 방식을 포함하여 카탈로그의 모든 지갑을 샌드박스에서 테스트할 수 있습니다. 시뮬레이션된 시도에는 요금이 청구되지 않습니다.

예시:

"decline_document_expired"

sign
object

이 세션에 대한 전자 서명 입력값입니다. documents는 서명할 문서이며, 전자 서명 단계가 세션에서 문서를 가져오는 워크플로(signature_documents_source가 session 또는 both)의 경우 최대 20개 문서 및 총 50MB까지 가능합니다. field_values는 워크플로 및 세션 문서 모두에서 prefill이 api.<key>인 필드를 채웁니다. 동일한 workflow_id 및 vendor_data로 세션을 다시 생성하면 대기 중인 세션이 반환됩니다. 해당 호출이 sign을 전송하는 경우 해당 문서, 필드 및 값은 첫 번째 호출과 동일해야 하며, 다를 경우 {"sign": "signature_document_changed"}와 함께 400이 반환됩니다. 전자 서명 문서를 참조하세요.

user_state
string

알려진 경우 해당 개인이 거주하는 위치: ISO 3166-2 세부 구역 코드(US-IL, ES-M) 또는 미국 주 코드나 이름(IL, Illinois). 법적으로 명시적인 생체 인증 동의를 요구하는 주(일리노이, 텍사스, 콜로라도)의 경우 인증 흐름에서 얼굴을 캡처하기 전에 declared_state 트리거와 함께 동의를 요청합니다. 인식할 수 없는 값은 400을 반환합니다. 생체 인증 동의를 참고하십시오.

Maximum string length: 16
예시:

"US-IL"

해당 인물로부터 이미 수집한 명시적 생체 인식 동의입니다. 요구사항을 충족하므로 인증 플로우에서 다시 묻지 않으며, 결정에는 트리거 customer_collected와 함께 status: "given"으로 기록됩니다. 사용자가 플로우에서 이미 제출한 답변은 대체되지 않습니다. 생체 인식 동의를 참고하십시오.

응답

세션이 생성되었습니다(또는 워크플로의 최신 게시 버전에 동일한 vendor_data를 가진 완료되지 않은 세션이 이미 존재하는 경우 해당 세션이 반환됨). 응답은 사용자를 리디렉션할 호스팅 인증 url을 포함하는 직렬화된 세션입니다.

session_id
string<uuid>
필수

인증 세션의 고유 식별자입니다. GET /v3/session/{sessionId}/decision/을 호출할 때 이 id를 사용합니다.

예시:

"11111111-2222-3333-4444-555555555555"

session_number
integer
필수

애플리케이션 내에서 세션에 할당된 사람이 읽기 쉬운 순차 번호입니다. 고객 지원 및 대시보드에 유용합니다.

예시:

43762

session_token
string
필수

최종 사용자가 url의 호스팅 인증 흐름에 접근할 수 있도록 권한을 부여하는 12자의 URL-safe token입니다. 세션이 만료될 때까지 유효합니다. 비밀 정보로 취급하십시오. 이 token을 보유한 사람은 누구나 해당 세션의 인증 흐름을 열 수 있습니다.

예시:

"3FaJ9wLqX2Mz"

url
string<uri>
필수

최종 사용자를 리디렉션할 호스팅 인증 URL입니다. URL에는 session_token이 포함되어 있으며, 구성된 경우 화이트 라벨 도메인을 사용합니다. 요청에 language가 포함되어 있으면 URL에 언어 경로 세그먼트(https://verify.didit.me/{language}/session/{session_token}, 예: /es/session/...)가 포함되고, language가 없으면 해당 세그먼트가 생략됩니다.

예시:

"https://verify.didit.me/session/3FaJ9wLqX2Mz"

vendor_data
string | null
필수

자체 시스템의 사용자 또는 기업과 세션을 연결하기 위해 요청에 전달한 식별자입니다. 입력한 그대로 반환됩니다. 제공되지 않은 경우 null입니다.

예시:

"user-123"

metadata
any
필수

세션 생성 시 함께 저장한 임의의 JSON payload입니다. 보낸 JSON 값(객체, 문자열, 숫자, 배열)이 그대로 반환되지만, JSON 객체를 사용하는 것이 좋습니다. 최종 사용자에게는 표시되지 않습니다. 응답에 항상 포함되며, 생성 시 제공되지 않은 경우 null입니다.

예시:
status
enum<string>
필수

세션의 현재 상태입니다. 새로 생성된 세션은 Not Started를 반환합니다. 워크플로의 최신 게시 버전에 동일한 vendor_data를 가진 완료되지 않은 세션이 이미 존재하는 경우, 반환되는 상태에는 해당 기존 세션의 상태가 반영됩니다.

사용 가능한 옵션:
Not Started,
In Progress,
Approved,
Declined,
In Review,
Expired,
Abandoned,
Kyc Expired,
Resubmitted,
Awaiting User
예시:

"Not Started"

callback
string<uri> | null
필수

사용자가 플로우를 완료한 후 이동하게 되는 최종 리디렉션 URL입니다. Didit은 이 URL에 ?verificationSessionId={session_id}&status={status}를 추가합니다. 요청에서 제공되지 않은 경우 워크플로에 구성된 콜백 URL로 대체되며, 둘 다 설정되지 않은 경우 null입니다. 애플리케이션에 허용된 도메인이 설정되어 있고 이 URL이 해당 도메인 외의 웹 URL인 경우(예: 목록이 변경되기 전에 설정된 워크플로 기본값), 호스팅 플로우는 사용자를 해당 URL로 리디렉션하지 않습니다.

예시:

"https://example.com/verification/callback"

workflow_id
string<uuid>
필수

이 세션이 실행되는 워크플로의 안정적인 식별자입니다. 항상 워크플로의 안정적인 그룹 식별자이며, 요청에서 특정 워크플로 버전 UUID를 참조했더라도(하위 호환성 조회) 응답에는 안정적인 workflow_id가 반환됩니다. 콘솔에서 구성한 워크플로와 세션을 연결하는 데 사용하세요.

예시:

"11111111-2222-3333-4444-555555555555"

workflow_version
integer
필수

세션 생성 시 고정된 게시된 워크플로 버전의 버전 번호입니다. Didit은 세션이 생성될 때 workflow_id를 워크플로의 최신 게시 버전에 매핑하며, 이후 워크플로가 다시 게시되더라도 세션은 해당 버전을 계속 실행합니다.

예시:

3

tags
string[]

세션의 태그를 이름으로 표시합니다.

예시:
마지막 수정일 2026년 11월 7일