연동매뉴얼

Java API

(Spring / SpringBoot / JSP)

Index

1. 본인인증 요청

2. 본인인증 상태 확인

3. 본인인증 검증

A. 객체정보

1. 본인인증 요청

본인인증 API 주의사항

  • 본인인증 서비스에서 이용기관이 생성하는 Token은 이용자가 전자서명할 원문이 됩니다. 이는 보안을 위해 1회용으로 생성해야 합니다.
  • 이용자는 이용기관이 생성한 1회용 토큰을 서명하고, 이용기관은 그 서명값을 검증함으로써 이용자에 대한 인증의 역할을 수행하게 됩니다.

1.1. RequestVerifyAuth - 본인인증 요청

· 카카오톡 이용자에게 본인인증을 요청합니다.

public String requestVerifyAuth(String ClientCode, RequestVerifyAuth verifyAuthRequest) throws KakaocertException

Parameter

순번 변수명 타입 길이 필수 설명
1 ClientCode String 12 O kakaoCert에 등록된 이용기관 코드
└ 관리자 사이트에서 확인가능
2 verifyAuthRequest RequestVerifyAuth - O 본인인증 요청 정보

Return

String - 접수아이디

Throws

KakaocertException

2. 본인인증 상태 확인

2.1. GetVerifyAuthState - 서명 상태 확인

· 본인인증 요청시 반환 받은 접수아이디를 통해 서명 상태를 확인합니다.

public ResultVerifyAuth getVerifyAuthState(String ClientCode, String receiptID) throws KakaocertException

유의사항

· 상태 확인하여'ResultVerifyAuth'의 'state'가 1(서명완료)인지 확인해야만, [3.1. VerifyAuth] 함수를 이용 할 수 있습니다.

Parameter

순번 변수명 타입 길이 필수 설명
1 ClientCode String 12 O kakaoCert에 등록된 이용기관 코드
└ 관리자 사이트에서 확인가능
2 receiptID String 20 O 본인인증 요청시 반환된 접수아이디

Return

ResultVerifyAuth

Throws

KakaocertException

3. 본인인증 검증

3.1. VerifyAuth - 서명 검증

· 본인인증 요청시 반환 받은 접수아이디에 해당하는 전자서명값을 검증하며, 전자서명 데이터 전문('signedData')을 반환 받습니다.

· 반환 받은 전자서명 데이터 전문('signedData')와 [1.1. RequestVerifyAuth] 함수 호출시 입력한 Token의 동일 여부를 확인하여 본인인증 검증을 완료합니다.

· 카카오페이 보안정책에 따라 검증 API는 1회만 호출할 수 있습니다. 재시도시 오류처리됩니다.

· 전자서명 완료일시로부터 30분 이내에 검증 API를 호출하지 않으면 오류가 반환됩니다.

public VerifyResult verifyAuth(String ClientCode, String receiptID) throws KakaocertException

유의사항

· 검증 전에 [2.1. GetVerifyAuthState] 함수를 통해 반환되는 'ResultVerifyAuth'의 'state'가 1(서명완료)인지 확인해야합니다.

Parameter

순번 변수명 타입 길이 필수 설명
1 ClientCode String 12 O kakaoCert에 등록된 이용기관 코드
└ 관리자 사이트에서 확인가능
2 receiptID String 20 O 본인인증 요청시 반환된 접수아이디

Return

VerifyResult

Throws

KakaocertException

A. 객체정보

A.1. KakaocertException - kakaoCert 예외 처리

순번 변수명 항목명 타입 길이 설명
1 code 코드 long - API 처리 실패에 대한 오류코드("-"로 시작하는 8자리 숫자값)
└ [참고] 오류코드
2 message 메시지 String - API 처리 실패에 대한 오류메시지

A.2. RequestVerifyAuth - 본인인증 요청 정보

순번 변수명 항목명 필수 타입 길이 설명
1 CallCenterNum 고객센터 전화번호 O String 20 카카오톡 인증메시지 중 "고객센터" 항목에 표시
2 CallCenterName 고객센터명 - String 10 카카오톡 인증메시지 중 "고객센터명" 항목에 표시
└ 미입력시 "이용기관명 + 고객센터"로 표시
3 Expires_in 인증요청 만료시간 O int - 최대 1000까지 입력 가능(권장 : 300), 단위 : 초(s)
└ 만료시간 안에 수신자가 미인증시, 'ResultVerifyAuth' 객체의 변수 'state'를 2 (만료) 처리
4 ReceiverBirthDay 수신자 생년월일 O String 8 형식 : YYYYMMDD
5 ReceiverHP 수신자 휴대폰번호 O String 11 하이픈(-) 제외하고 입력
6 ReceiverName 수신자 성명 O String 80 국문 최대 26자, 영문 최대 80자까지 입력가능
7 Token 원문 O String 500 ※ 보안을 위해 1회용으로 생성
8 TMSTitle 인증요청 메시지 제목 O String 40 카카오톡 인증메시지 중 "요청구분" 항목에 표시
9 TMSMessage 인증요청 메시지 부가내용 - String 500 카카오톡 인증메시지 중 상단에 표시
10 SubClientID 별칭코드 - String 12 관리자 사이트에서 이용기관이 등록한 별칭에 대한 코드
└ 카카오톡 인증메시지 중 "요청기관" 항목에 표시
└ 미입력시 이용기관명이 "요청기관" 항목에 표시
11 isAllowSimpleRegistYN 인증서 발급유형 선택 O boolean - true / false 중 택 1
└ true = 휴대폰 본인인증만을 이용해 인증서 발급
└ false = 본인계좌 점유 인증을 이용해 인증서 발급
12 isVerifyNameYN 수신자 실명확인 여부 O boolean - true / false 중 택 1
└ true = 확인, false = 미확인
└ 카카오페이가 본인인증을 통해 확보한 이용자 실명과 {@no.6 ReceiverName} 값과 비교하여 실명 확인함
13 PayLoad 메모 - String 200 메모의 목적으로 이용, 이용기관이 생성한 값
└ 개인정보 관련 항목 입력되지 않도록 주의

A.3. ResultVerifyAuth - 서명 상태 정보

순번 변수명 항목명 타입 길이 설명
1 receiptID 접수아이디 String 20 RequestVerifyAuth 함수 호출시 반환 받은 값
2 clientCode 이용기관코드 String 12 RequestVerifyAuth 함수 호출시 파라미터로 입력한 'ClientCode' 값
3 clientName 이용기관명 String 80 {@no.2 clientCode}에 해당하는 이용기관 이름
└ 관리자 사이트에서 확인 가능
4 subClientName 별칭 String 80 {@no.5 subClientCode}에 해당하는 별칭 이름
5 subClientCode 별칭코드 String 12 RequestVerifyAuth 함수 호출시 입력한 'RequestVerifyAuth' 객체의 'SubClientID' 값
└ 이 함수 호출시 값을 입력하지 않은 경우 null 반환
6 state 상태 int - 0 / 1 / 2 중 반환
└ 0 = 미확인, 1 = 서명완료, 2 = 만료
7 expires_in 인증요청 만료시간(초) int - RequestVerifyAuth 함수 호출시 입력한 'RequestVerifyAuth' 객체의 'Expires_in' 값
└ 만료시간 안에 수신자가 미인증시, {@no.6 state}를 2 (만료) 처리
8 callCenterNum 고객센터 전화번호 String 20 RequestVerifyAuth 함수 호출시 입력한 'RequestVerifyAuth' 객체의 'CallCenterNum' 값
9 callCenterName 고객센터명 String 10 RequestVerifyAuth 함수 호출시 입력한 'RequestVerifyAuth' 객체의 'CallCenterName' 값
10 tmstitle 인증요청 메시지 제목 String 40 RequestVerifyAuth 함수 호출시 입력한 'RequestVerifyAuth' 객체의 'TMSTitle' 값
11 tmsmessage 인증요청 메시지 부가내용 String 500 RequestVerifyAuth 함수 호출시 입력한 'RequestVerifyAuth' 객체의 'TMSMessage' 값
12 allowSimpleRegistYN 인증서 발급유형 선택 boolean - RequestVerifyAuth 함수 호출시 입력한 'RequestVerifyAuth' 객체의 'isAllowSimpleRegistYN' 값
└ true / false 중 반환
└ true = 휴대폰 본인인증만을 이용해 인증서 발급
└ false = 본인계좌 점유 인증을 이용해 인증서 발급
13 verifyNameYN 수신자 실명확인 여부 boolean - RequestVerifyAuth 함수 호출시 입력한 'RequestVerifyAuth' 객체의 'isVerifyNameYN' 값
└ true (확인) / false (미확인) 중 반환
└ 카카오페이가 본인인증을 통해 확보한 이용자 실명과 RequestVerifyAuth 함수 호출시 입력한 'RequestVerifyAuth' 객체의 'ReceiverName' 값과 비교하여 실명 확인함
14 requestDT 카카오 인증서버 등록일시 String 14 형식 : yyyyMMddHHmmss
15 expireDT 인증 만료일시 String 14 형식 : yyyyMMddHHmmss
16 regDT 인증요청 등록일시 String 14 형식 : yyyyMMddHHmmss
17 viewDT 수신자 카카오톡 인증메시지 확인일시 String 14 형식 : yyyyMMddHHmmss
18 completeDT 수신자 카카오톡 전자서명 완료일시 String 14 형식 : yyyyMMddHHmmss
19 verifyDT 서명 검증일시 String 14 형식 : yyyyMMddHHmmss
20 payload 메모 String 200 RequestVerifyAuth 함수 호출시 입력한 'RequestVerifyAuth' 객체의 'PayLoad' 값

A.4. VerifyResult - VerifyAuth 응답 정보

순번 변수명 항목명 타입 길이 설명
1 receiptId 접수아이디 String 20 본인인증 요청을 식별하기 위해 kakaoCert에서 할당한 값
2 signedData 전자서명 데이터 전문 String 500 -