본인인증 API

패스 앱을 이용하여 이용자의 개인정보(이름, 생년월일, 휴대폰번호)로 개인의 본인명의 유무를 확인하는 패스 본인인증 API 입니다. 개발하는 웹/앱 방식에 따라 패스 앱으로 푸시(Push) 인증 메시지를 전송하여 인증하는 “푸시(Push) 인증”과 이용기관 앱에서 패스 앱을 실행하여 패스 인증 메시지 전송없이 비밀번호 입력만으로 인증하는 “앱투앱 인증” 방식 중 선택하여 연동할 수 있습니다.

1. RequestIdentity - 본인인증 요청

패스 이용자에게 본인인증을 요청합니다.
앱투앱 인증 방식을 이용하는 이용기관은 [앱스킴 호출] 을 참고하여 주시기 바랍니다.

public IdentityReceipt requestIdentity(string clientCode, Identity identity)

Parameter

순번	변수명	타입	길이	필수	설명
	clientCode	string	12	Y	이용기관 코드
	identity	Identity	-	Y	본인인증 요청 정보

Return IdentityReceipt Throws BarocertException

2. GetIdentityStatus - 본인인증 상태확인

본인인증 요청 후 반환받은 접수아이디로 본인인증 진행 상태를 확인합니다.
상태확인 함수는 본인인증 요청 함수를 호출한 당일 23시 59분 59초까지만 호출 가능합니다.
본인인증 요청 함수를 호출한 당일 23시 59분 59초 이후 상태확인 함수를 호출할 경우 오류가 반환됩니다.

public IdentityStatus getIdentityStatus(string clientCode, string receiptID)

Parameter

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

Return IdentityStatus Throws BarocertException

3. VerifyIdentity - 본인인증 검증

완료된 전자서명을 검증하고 전자서명값(signedData)을 반환 받습니다.
검증 함수는 본인인증 요청 함수를 호출한 당일 23시 59분 59초까지만 호출 가능합니다.
본인인증 요청 함수를 호출한 당일 23시 59분 59초 이후 검증 함수를 호출할 경우 오류가 반환됩니다.
패스 보안정책에 따라 검증 API는 1회만 호출할 수 있습니다. 재시도시 오류가 반환됩니다.

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

public IdentityResult verifyIdentity(string clientCode, string receiptID, IdentityVerify identityVerify)

Parameter

변수명	타입	길이	필수	설명
clientCode	string	12	Y	이용기관 코드
receiptID	string	32	Y	접수 아이디
identityVerify	IdentityVerify	-	Y	본인인증 서명검증 요청정보

Return IdentityResult Throws BarocertException

4. 앱스킴 호출

4.1 Android

본인인증을 요청하기 위하여 이용기관은 이용기관 App 에서 패스 App 앱스킴을 호출합니다.
패스 App 앱스킴 호출시 입력한 callbackScheme으로 이용자의 전자서명 결과값 [ResponseCode]를 반환 받습니다.

{scheme}&callbackScheme={clientAppScheme}&packageName={clientPackageName}

Parameter

변수명	타입	길이	필수	설명
scheme	string	-	Y	본인인증 요청시 반환된 앱스킴
clientAppScheme	string	-	Y	패스 앱 인증완료 후 호출될 이용기관 앱스킴
clientPackageName	string	-	Y	패스 앱 인증완료 후 호출될 이용기관 앱패키지명

Return {clientAppScheme}://?code={ResponseCode}

4.2 iOS

본인인증을 요청하기 위하여 이용기관은 이용기관 App 에서 패스 App 앱스킴을 호출합니다.
패스 App 앱스킴 호출시 입력한 callbackScheme으로 이용자의 전자서명 결과값 [ResponseCode]를 반환 받습니다.

{scheme}&callbackScheme={clientAppScheme}

Parameter

순번	변수명	타입	길이	필수	설명
	scheme	string	-	Y	본인인증 요청시 반환된 앱스킴
	clientAppScheme	string	-	Y	패스 앱 인증완료 후 호출될 이용기관 앱스킴

Return {clientAppScheme}://?code={ResponseCode}

4.3 ResponseCode

순번	code	설명
	E0000	성공
	E3001	패스 서비스 미가입자
	E3002	패스 인증서 미발급자
	E3003	사용자 인증 시 취소 또는 서명 과정 중 취소
	E3004	사용자 인증 시 인증 실패 (생체 인증 실패 등)
	E3005	단말 네트워크 환경 등으로 인한 통신 실패
	E3006	통신사 서버에서 에러 발생
	E3007	인증서 Library 서명에서 에러 발생
	E3999	기타 오류

5. 객체정보

5.1. BarocertException

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

5.2. Identity

변수명	타입	길이	필수	설명
receiverHP	string	11	Y	수신자 휴대폰번호 → 하이픈(-) 제외하고 입력
receiverName	string	80	Y	수신자 성명
receiverBirthday	string	8	N	수신자 생년월일 → 형식: yyyyMMdd
reqTitle	string	40	Y	인증요청 메시지 제목
reqMessage	string	500	Y	인증요청 메시지 내용
callCenterNum	string	12	Y	고객센터 연락처
expireIn	int	4	Y	요청 만료시간 → 최대: 1000초(s) / 권장: 300초(s)
token	string	2800	Y	원문
userAgreementYN	bool	-	N	사용자 동의 필요 여부 └True필요 └False불필요 : 기본값
receiverInfoYN	bool?	-	N	사용자 정보 포함 여부 └True포함 : 기본값 └False불포함
appUseYN	bool	-	N	앱투앱 인증 방식 이용 여부 └True앱투앱 인증[앱스킴 호출] └False푸시(Push) 인증 : 기본값
telcoType	string	3	조건부	통신사 유형 └SKT └KT └LGU appUseYN=True 경우 필수
deviceOSType	string	7	조건부	모바일장비 운영체제 └ANDROID └IOS appUseYN=True 경우 필수

5.3. IdentityVerify

순번	변수명	타입	길이	필수	설명
	receiverHP	string	11	Y	수신자 휴대폰번호 → 하이픈(-) 제외하고 입력
	receiverName	string	80	Y	수신자 성명

5.4. IdentityReceipt

변수명	타입	길이	필수	설명
receiptID	string	32	Y	접수아이디
scheme	string	100	N	앱스킴 appUseYN=True 경우 반환
marketUrl	string	-	N	앱 다운로드 URL appUseYN=True 경우 반환

5.5. IdentityStatus

변수명	타입	길이	필수	설명
receiptID	string	32	Y	접수아이디
clientCode	string	12	Y	이용기관 코드
state	int	1	Y	상태 └0대기 └1완료 └2만료 └3거절 └4실패 └5미처리
requestDT	string	14	Y	전자서명 요청일시 → 형식: yyyyMMddHHmmss
completeDT	string	14	N	전자서명 완료일시 → 형식: yyyyMMddHHmmss
expireDT	string	14	Y	전자서명 만료일시 → 형식: yyyyMMddHHmmss
rejectDT	string	14	N	전자서명 거절일시 → 형식: yyyyMMddHHmmss

5.6. IdentityResult

변수명	타입	길이	필수	설명
receiptID	string	32	Y	접수아이디
state	int	1	Y	상태 └0대기 └1완료 └2만료 └3거절 └4실패 └5미처리
receiverName	string	80	N	RSA 암호화 수신자 성명 receiverInfoYN=True 경우 반환
receiverYear	string	4	N	RSA 암호화 수신자 출생년도 → 형식 : yyyy receiverInfoYN=True 경우 반환
receiverDay	string	4	N	RSA 암호화 수신자 출생월일 → 형식 : MMdd receiverInfoYN=True 경우 반환
receiverGender	string	1	N	RSA 암호화 수신자 성별 └M남성 └F여성 receiverInfoYN=True 경우 반환
receiverForeign	string	1	N	RSA 암호화 외국인 여부 └Y외국인 └N내국인 receiverInfoYN=True 경우 반환
receiverTelcoType	string	3	N	RSA 암호화 통신사 유형 └SKT └KT └LGU receiverInfoYN=True 경우 반환
signedData	string	-	Y	전자서명값
ci	string	-	Y	RSA 암호화 CI