블로그 · 2026년 5월 21일

KYB 세션 수명 주기: 상태 및 웹훅 (KO)

KYB 인증의 시작부터 끝까지 — 세션 상태, 기능별 상태, 사업체 상태, 그리고 기록을 동기화하는 웹훅까지 — 회사당 $2.00로 추적하세요.

작성자: Didit2026년 5월 21일업데이트됨 2026년 5월 21일

KYB 인증은 단순한 예/아니요 답변이 아니라 여러 단계로 이루어진 과정입니다. 등록 조회는 즉시 승인될 수 있지만, 문서 인증은 재제출을 기다려야 하고, 법인 AML은 분석가 검토를 위해 대기할 수 있습니다. KYB를 깔끔하게 통합하려면 인증의 모든 부분이 어떤 상태인지 정확히 알아야 하며, 이러한 상태가 변경되는 순간 자체 시스템을 업데이트해야 합니다. 이것이 바로 세션 수명 주기와 웹훅이 필요한 이유입니다.

Didit의 비즈니스 인증 API는 전체 상태 머신을 노출합니다. 전체 세션 상태, 각 기능별 상태, 일단 관리 대상이 되면 사업체에 대한 별도의 상태 집합, 그리고 모든 변경 사항에 대해 실행되는 웹훅을 제공합니다. 전체 회사 인증 비용은 $2.00이며, 이 가이드는 전체 수명 주기 — 모든 상태, 모든 웹훅, 그리고 이를 연결하는 관리 API —를 설명합니다.

주요 내용

세 가지 상태 계층. KYB 인증은 세션 상태, 기능별 상태, 그리고 일단 관리되면 사업체 상태를 가집니다.
여덟 가지 세션 상태. NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.
네 가지 KYB 기능 각각에 대한 여섯 가지 기능 상태: NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, AWAITING_USER.
관리 대상에 대한 세 가지 법인 상태: ACTIVE, FLAGGED, BLOCKED.
모든 것에 대한 웹훅. 세션의 경우 status.updated 및 data.updated (session_kind: business 포함); 관리 대상 법인의 경우 business.status.updated 및 business.data.updated.
전체 관리 API — POST /v3/businesses/create/, GET /v3/businesses/, GET /v3/businesses/{vendor_data}/, PATCH .../update-status/.

KYB 수명 주기가 다루는 내용

KYB 인증은 세 가지 계층에서 상태를 생성하며, 각 계층은 다른 질문에 답합니다.

세션은 "전체적으로 인증이 어떻게 진행되고 있는가?"에 답합니다.
각 기능은 "등록 / 회사 AML / 문서 / 주요 인물 확인은 어디까지 진행되었는가?"에 답합니다.
사업체는 "현재 우리 시스템에서 이 회사의 운영 상태는 어떤가?"에 답합니다.

이 세 가지를 모두 읽고, 폴링 대신 웹훅으로 동기화를 유지합니다. 인증은 세션으로 시작하여 기능을 해결하고, 전반적인 결과에 도달한 다음 — 회사를 관리하기 시작하면 — 상황이 변경됨에 따라 사용자가 제어하는 사업체 상태를 가집니다.

왜 중요한가

세분화된 상태가 없으면 KYB 통합은 추측으로 전락합니다. 단일 "대기 중" 플래그는 어떤 검사가 지연시키고 있는지, 또는 어떤 조치가 이를 해제할 수 있는지에 대해 아무것도 알려주지 않습니다. 기능별 상태를 사용하면 전체 인증을 실패시키는 대신, 지원자에게 문서를 재제출하도록 요청하거나, 분석가 검토를 위해 법인 AML 일치를 대기열에 추가하거나, UBO에게 KYC를 완료하도록 요청하는 등 정확하게 라우팅할 수 있습니다.

웹훅이 중요한 이유는 KYB가 비동기적이기 때문입니다. 등록 데이터, 문서 OCR, 스크리닝 결과는 다른 시간에 도착하며, 사람의 검토는 더 오래 걸립니다. 변경 사항을 폴링하는 것은 낭비적이고 느립니다. 웹훅은 변경 사항이 발생하는 즉시 푸시하여, cron 작업이 API를 계속 호출하지 않고도 기록이 현실을 반영하도록 합니다.

기술적 세부 사항

KYB 세션은 통합 /v3/ API에 대해 생성되며 수명 주기 상태를 다시 보고합니다.

curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "your_kyb_workflow_id",
    "vendor_data": "merchant_6601",
    "callback": "https://yourapp.com/kyb/callback"
  }'

status.updated 웹훅은 세션 상태와 기능별 상태를 전달합니다.

{
  "event": "status.updated",
  "session_kind": "business",
  "session_id": "kyb_3a90f1c2",
  "vendor_data": "merchant_6601",
  "status": "IN_REVIEW",
  "features": {
    "kyb_registry": "APPROVED",
    "kyb_company_aml": "IN_REVIEW",
    "kyb_documents": "RESUB_REQUESTED",
    "kyb_key_people": "APPROVED"
  }
}

세션 상태. NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.

기능 상태. kyb_registry, kyb_company_aml, kyb_documents, kyb_key_people 각각은 다음 중 하나를 보고합니다: NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED, AWAITING_USER.

웹훅. 세션의 경우: status.updated (수명 주기 변경) 및 data.updated (강화된 데이터), 둘 다 session_kind: "business"를 포함합니다. 관리 대상 법인의 경우: business.status.updated 및 business.data.updated.

가격. 회사 인증당 $2.00.

사업체 관리

회사가 인증되면 비즈니스 API를 통해 관리하는 법인이 됩니다.

POST /v3/businesses/create/ — 사업체 등록.
GET /v3/businesses/ — 관리 대상 비즈니스 목록 조회.
GET /v3/businesses/{vendor_data}/ — vendor_data 참조로 하나의 비즈니스 가져오기.
PATCH .../update-status/ — 법인 상태 변경.

법인은 인증 세션과 독립적인 자체 상태를 가집니다: ACTIVE (양호한 상태), FLAGGED (위험 신호에 대한 검토 중), 또는 BLOCKED (정지됨). 이것은 운영 계층입니다. 회사는 APPROVED 세션을 완료한 후 모니터링에서 무언가가 발견되어 FLAGGED될 수 있습니다. 법인 변경 사항은 business.status.updated 및 business.data.updated를 발생시켜 하위 시스템이 최신 상태를 유지하도록 합니다.

시작부터 끝까지의 수명 주기

일반적인 인증은 계층을 순서대로 진행합니다. 세션은 NOT_STARTED로 시작하여 기능이 실행됨에 따라 IN_PROGRESS로 이동하고, 각 기능이 해결됩니다 — 등록은 APPROVED, 문서는 깔끔한 업로드가 도착할 때까지 RESUB_REQUESTED, 회사 AML은 분석가가 일치를 승인할 때까지 IN_REVIEW, 주요 인물은 APPROVED. 모든 기능이 완료되면 세션은 APPROVED, DECLINED 또는 IN_REVIEW로 결정됩니다. 그 시점부터 회사는 ACTIVE 법인으로 관리되기 시작하며, 지속적인 감독에 따라 나중에 FLAGGED 또는 BLOCKED로 상태가 변경될 수 있습니다. 각 전환은 웹훅을 통해 사용자에게 푸시됩니다.

사용 사례

마켓플레이스는 판매자를 정확하게 라우팅합니다: 전체 온보딩을 실패시키지 않고 문서를 재제출하거나, UBO의 KYC를 완료하거나, 법인 AML 일치를 보류합니다.
핀테크 및 뱅킹 플랫폼은 폴링 대신 웹훅으로 법인 계정 기록을 동기화하고, 위험이 변경됨에 따라 법인을 플래그 지정하거나 차단합니다.
대출 제공업체는 각 심사 확인의 상태를 추적하고 관리 API를 통해 대출자 상태를 업데이트합니다.
암호화폐 B2B 플랫폼은 인증부터 지속적인 상태에 이르기까지 모든 거래 상대방 법인의 감사 가능한 수명 주기를 유지합니다.

Didit과 통합하는 방법

워크플로 구축. 비즈니스 콘솔에서 필요한 기능을 갖춘 KYB 워크플로를 생성합니다.
세션 생성. KYB workflow_id 및 vendor_data 참조를 사용하여 POST /v3/session/을 호출합니다.
웹훅 구독. 세션의 경우 status.updated 및 data.updated (session_kind: business)를 처리하고, 관리 대상 법인의 경우 business.status.updated / business.data.updated를 처리합니다.
법인 관리. POST /v3/businesses/create/, GET /v3/businesses/, GET /v3/businesses/{vendor_data}/, PATCH .../update-status/를 사용하여 각 회사를 ACTIVE, FLAGGED 또는 BLOCKED로 유지합니다.

모든 것이 통합 /v3/ API에 있으므로, 동일한 수명 주기 모델이 KYC, 모니터링 및 KYB에 걸쳐 적용됩니다. 전체 신원 및 사기 방지 플랫폼을 위한 하나의 일관된 상태 머신입니다.

자주 묻는 질문

KYB 세션 상태는 무엇인가요?

NOT_STARTED, IN_PROGRESS, APPROVED, DECLINED, IN_REVIEW, RESUBMITTED, ABANDONED, EXPIRED.

개별 기능은 어떤 상태를 보고하나요?

kyb_registry, kyb_company_aml, kyb_documents, kyb_key_people 각각은 NOT_FINISHED, APPROVED, DECLINED, IN_REVIEW, RESUB_REQUESTED 또는 AWAITING_USER를 보고합니다.

어떤 웹훅을 구독해야 하나요?

세션의 경우 status.updated 및 data.updated (session_kind: business). 관리 대상 사업체의 경우 business.status.updated 및 business.data.updated.

인증 후 회사의 상태를 어떻게 변경하나요?

관리 API — PATCH .../update-status/ —를 사용하여 법인을 ACTIVE, FLAGGED 또는 BLOCKED로 설정합니다.

KYB 인증 비용은 얼마인가요?

전체 인증 (등록, UBO, 임원, 법인 AML)의 경우 회사당 $2.00입니다.

시작할 준비가 되셨나요?

문서에서 비즈니스 인증 개요를 읽고, 비즈니스 인증 제품 페이지에서 플랫폼의 나머지 부분과 어떻게 맞는지 확인하고, 가격 페이지에서 투명한 호출당 가격을 확인하세요. 준비가 되면 무료로 시작하세요 — 매월 500건의 무료 KYC 확인과 회사당 $2.00의 비즈니스 인증을 제공합니다.