TomoIDV Developer Document

<aside>

</aside>

Intro : 소개

TomoIDV는 방한 외국인의 자국 발행 신분증 기반 eKYC flow를 제공하는 API Service 입니다.

이 문서는 TomoIDV API를 사용하기 위한 OAuth2 인증, KYC 정책 선택, KYC 시작, KYC flow, 결과 조회까지 하나의 온보딩 흐름으로 정의합니다.

sequenceDiagram
	participant ClientApp as Client App
	participant ClientServer as Client Server
	participant IDVServer as TomoIDV Server
	participant IDVApp as TomoIDV App

	ClientServer->>+IDVServer: [1] Get Access Token (POST /v1/oauth2/token)
	IDVServer-->>-ClientServer: 200 OK
	ClientApp->>+ClientServer: Start IDV
	ClientServer->>+IDVServer: [2] Start IDV(Get IDV URL) (POST /v1/idv/start)
	IDVServer-->>-ClientServer: 200 OK
	ClientServer-->>-ClientApp: 200 OK
	ClientApp->>IDVApp: [3] Launch IDV App
	IDVApp-->>ClientApp: [4] Return to Origin App
	ClientServer->>+IDVServer: [5] Get Kyc (POST /v1/idv/result)
	IDVServer->>-ClientServer: 200 OK

용어	의미
`client_id`	대시보드에서 생성한 API 클라이언트 식별자
secret/key material	`client_assertion` JWT를 서명하는 백엔드 전용 인증 정보
`client_assertion`	OAuth2 토큰 요청에 제출하는 클라이언트 서명 JWT
`access_token`	IDV 서버 API 호출에 사용하는 Bearer 토큰
`kyc_policy`	KYC 방식과 소유자 확인 수준을 지정하는 공개 정책 객체
`policy_key`	서버가 완료된 정책을 식별할 때 반환하는 정규 키
`ppid` / PPID	KYC 완료 후 발급되는 영속 고유값

Requirement

TLS 1.3 (TLS 1.1, TLS 1.2는 지원하지않습니다.)

API 사용 준비

1. Client id, Secret key 발급

API를 사용하기 위해서는 client id, secret key를 발급 받아야합니다. 이는 OAuth2.0 인증에 사용되며, Console 에서 발급합니다. 발급과정은 [Register client] 문서를 참고해주시기 바랍니다. client id와 secret key를 발급 받으면, Access token을 발급 받을 수 있습니다. 이 Access Token을 이용하여 TomoIDV API를 사용하실 수 있습니다.

개발자 콘솔	URL	설명
Sandbox Console	`https://test-console.tomopayment.com`	실제 신분증증이 아닌 sandbox 모드로 KYC flow를 지원하는 Test용 Console
Production Console	`https://console.tomopayment.com`	실제 신분증(외국인)으로 production KYC flow를 지원하는 운영용 Console

2. API Base Url

TomoIDV는 Sandbox, Production 두 가지 Domain(Base url)을 사용하고 있습니다. Sandbox Console 에서 만들어진 client id는 Sandbox Base URL, Production Console 에서 만들어진 client id는 Production Base URL을 사용 할 수 있습니다.

API 환경	IDV API base URL
샌드박스(sandbox)	`https://test.tomopayment.com`
운영(production)	`https://api.tomopayment.com`

3. OAuth2 Access Token 발급

POST /v1/oauth2/token
Content-Type: application/x-www-form-urlencoded

Request body

필드	타입	필수 여부	값
`grant_type`	string	필수	`client_credentials`
`client_assertion_type`	string	필수	`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
`client_assertion`	string	필수	클라이언트가 서명한 `client_assertion` (JWT)
`scope`	string	선택	`idv.read` (`idv.read`: 생략 시 기본 값)
`resource`	string	선택	`null` (지금은 사용하지 않음)