KYB 연동 가이드: 아키텍처 및 패턴

​

아키텍처

​

인증

​

세션 생성

​

호스팅 링크 전달

• 자체 플랫폼에서 이메일로 보냅니다.
• 온보딩 UI에 링크로 삽입합니다.
• 앱 내 웹뷰(iOS / Android / React Native)에서 엽니다.

​

폴링과 webhook

• 지수 백오프를 적용해 GET /v3/session/{id}/decision/을 폴링합니다. 처음에는 10초마다, 최대 60초 간격까지 늘립니다.
• status가 "Approved", "Declined", "In Review" 중 하나이면 폴링을 중단합니다.

​

Webhook 처리

• status.updated: 세션 상태가 변경되었습니다. KYB 세션을 필터링하려면 session_kind === "business"를 조건으로 사용하세요.
• data.updated: 검토자가 콘솔에서 등기 데이터나 주요 인물 정보를 수정했거나, 등기부에서 변경을 보고한 경우입니다. 신청자가 문서를 업로드하거나 주요 인물을 제출할 때는 전송되지 않으므로, 그 경우에는 status.updated를 따르세요. 같은 session_kind 필터를 적용합니다.
• business.status.updated / business.data.updated: 연결된 기업 엔티티가 변경되었습니다.

​

결정 처리

switch (decision.status) {
  case 'Approved':
    await onboardBusiness(decision);
    break;
  case 'Declined':
    // The KYB decision has no single reason code: collectWarnings is your helper
    // that flattens warnings[] from registry_checks, document_verifications,
    // key_people_checks and aml_screenings
    await logRejection(collectWarnings(decision), decision);
    break;
  case 'In Review':
    // Wait for analyst decision — another webhook will fire
    await markPending(decision);
    break;
  case 'Resubmitted':
    // The business was asked to re-upload a document
    await notifyBusiness(decision);
    break;
}

​

재제출 흐름

• 같은 url을 다시 전달하세요. 호스팅 플로우는 재제출이 필요한 지점부터 이어서 진행됩니다.
• 사용할 수 없게 된 주요 인물 링크를 다시 발급하세요. 하위 KYC 세션이 삭제되었거나 해당 인물이 시작하기 전에 만료된 당사자에게는 주요 인물 KYC 세션 재생성으로 새 세션을 받을 수 있습니다.
• Business Console에서 케이스를 열어 내부적으로 주고받는 과정을 추적하세요.

​

자체 프런트엔드에서 단계 실행

1. 세션이 KYB 문서 단계에 있는 동안 법인 문서를 업로드하세요.
2. 주주를 포함해 문서에 명시된 당사자와 소유 비율을 읽고, 신청자에게 보여 주세요.
3. 당사자 초안을 생성, 수정, 삭제할 수 있습니다. 초안은 신고된 상태가 아니며 비용이 발생하지 않습니다.
4. 초안을 제출하세요. Didit이 검증해야 할 당사자를 결정하고, 각 당사자에 대해 KYC 세션을 생성한 뒤 kyc_session_url을 반환합니다. 이 URL을 전송하거나 삽입하면 됩니다.
5. 호스팅 플로우와 마찬가지로 세션에서 통합 결정을 읽으세요.

​

기업 프로필 집계

• 주기적인 KYB 재검증이 같은 프로필에 누적됩니다.
• 같은 vendor_data로 모니터링되는 거래에는 기업의 위험 맥락이 함께 포함됩니다.
• 사용자 엔티티에 연결된 실소유자와 임원이 엔티티 간 관계를 채웁니다.

​

모범 사례

​

오류 처리

​

다음 단계