본인확인 API

토스 앱을 사용하여 개인을 식별할 수 있는 고유 식별번호인 CI와 중복을 식별할 수 있는 DI를 확인하는 토스 본인확인 API 입니다. 개발하는 웹/앱 방식에 따라 토스 앱으로 푸시(Push) 인증 메시지를 전송하여 인증하는 “푸시(Push) 인증”과 이용기관 앱에서 토스 앱을 실행하여 토스 인증 메시지 전송없이 비밀번호 입력만으로 인증하는 “앱투앱 인증” 방식 중 선택하여 연동할 수 있습니다.

1. RequestUserIdentity - 본인확인 요청

토스 이용자에게 본인확인를 요청합니다.

function requestUserIdentity($clientCode, $UserIdentity)

Parameter

순번	변수명	타입	길이	필수	설명
	clientCode	String	12	Y	이용기관 코드
	UserIdentity	UserIdentity	-	Y	본인확인 요청 정보

Return UserIdentityReceipt Throws BarocertException

2. GetUserIdentityStatus - 본인확인 상태확인

본인확인 요청 후 반환받은 접수아이디로 인증 진행 상태를 확인합니다.

function getUserIdentityStatus($clientCode, $receiptID)

Parameter

순번	변수명	타입	길이	필수	설명
	clientCode	String	12	Y	이용기관 코드
	receiptID	String	32	Y	접수 아이디

Return UserIdentityStatus Throws BarocertException

3. VerifyUserIdentity - 본인확인 검증

완료된 전자서명을 검증하고 전자서명값(signedData)을 반환 받습니다.
반환받은 전자서명값(signedData)과 [1. RequestUserIdentity] 함수 호출에 입력한 Token의 동일 여부를 확인하여 이용자의 본인확인 검증을 완료합니다.
토스 보안정책에 따라 검증 API는 2회만 호출할 수 있습니다. 재시도시 오류가 반환됩니다.
전자서명 만료일시 이후에 검증 API를 호출하면 오류가 반환됩니다.

이용기관 서버에서는 본인확인 검증을 통해 반환받은 이용자의 개인정보(CI, 성명, 생년월일 등)와 전자서명을 요청한 이용자의 개인정보를 비교해 올바른 이용자인지 검증해야 합니다.

function verifyUserIdentity($clientCode, $receiptID)

Parameter

순번	변수명	타입	길이	필수	설명
	clientCode	String	12	Y	이용기관 코드
	receiptID	String	32	Y	접수 아이디

Return UserIdentityResult Throws BarocertException

4. 객체정보

4.1. BarocertException

순번	변수명	타입	길이	필수	설명
	Code	Long	-	Y	API 처리에 대한 응답코드
	message	String	-	Y	API 처리에 대한 응답메시지

4.2. UserIdentity

변수명	타입	길이	필수	설명
receiverHP	String	11	Y	AES 암호화 수신자 휴대폰번호 → 하이픈(-) 제외하고 입력
receiverName	String	80	Y	AES 암호화 수신자 성명
receiverBirthday	String	8	Y	AES 암호화 수신자 생년월일 → 형식: yyyyMMdd
token	String	50	Y	AES 암호화 원문 → 임의의 난수
expireIn	Integer	4	Y	요청 만료시간 → 최대: 1,800초(s) / 권장: 300초(s)
appUseYN	Boolean	-	N	앱투앱 인증 방식 이용 여부 └True앱투앱 인증 └False푸시(Push) 인증 : 기본값
deviceOSType	String	7	조건부	모바일장비 운영체제 └ANDROID └IOS appUseYN=True 경우 필수
returnURL	String	1000	조건부	복귀 URL → 앱투앱 인증 이용시 호출할 URL 또는 앱스킴 appUseYN=True 경우 필수

4.3. UserIdentityReceipt

순번	변수명	타입	길이	필수	설명
	receiptID	String	32	Y	접수아이디
	scheme	String	-	N	앱스킴 appUseYN=True 경우 반환

4.4. UserIdentityStatus

변수명	타입	길이	필수	설명
receiptID	String	32	Y	접수아이디
clientCode	String	12	Y	이용기관 코드
state	Integer	1	Y	상태 └0대기 └1완료 └2만료
expireDT	String	14	Y	전자서명 만료일시 → 형식: yyyyMMddHHmmss

4.5. UserIdentityResult

변수명	타입	길이	필수	설명
receiptID	String	32	Y	접수아이디
state	Integer	1	Y	상태 └0대기 └1완료 └2만료
receiverName	String	80	Y	AES 암호화 AES 암호화 수신자 성명
receiverYear	String	4	Y	AES 암호화 수신자 출생년도 → 형식 : yyyy
receiverDay	String	4	Y	AES 암호화 수신자 출생월일 → 형식 : MMdd
receiverGender	String	6	N	AES 암호화 수신자 성별 └MALE남성 └FEMALE여성
receiverForeign	String	9	N	AES 암호화 외국인 여부 └FOREIGNER외국인 └LOCAL내국인
receiverAgeGroup	String	5	N	AES 암호화 성인 여부 └ADULT성인 └MINOR미성년자
signedData	String	-	Y	전자서명값
ci	String	-	N	AES 암호화 CI
di	String	-	N	AES 암호화 DI