연동매뉴얼

ASP API

1. 전자서명 요청

1.1. RequestESign - 전자서명 요청

· 카카오톡 이용자에게 전자서명을 요청합니다.

Public Function RequestESign(ClientCode, ByRef RequestESignObj, IsAppUseYN)

유의사항

· App to App 방식을 이용할 경우 {@no.3 IsAppUseYN}에 True를 입력해야 합니다. [참고] App to App 방식

Parameter

순번 변수명 타입 길이 필수 설명
1 ClientCode String 12 O kakaoCert에 등록된 이용기관 코드
관리자 사이트에서 확인가능
2 RequestESignObj RequestESignObj - O 전자서명 요청 정보
3 IsAppUseYN Boolean - App to App 방식 이용 여부 : True / False 중 택 1
└ True = App To App 방식, False = Talk Message 방식(기본값)

Return

ResponseESign

Throws

Err

2. 전자서명 상태 확인

2.1. GetESignState - 서명 상태 확인

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

Public Function GetESignState(ClientCode, ReceiptID)

유의사항

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

Parameter

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

Return

ResultESignObj

Throws

Err

3. 전자서명 검증

3.1. VerifyESign - 서명 검증

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

Public Function VerifyESign(ClientCode, ReceiptID, Signature)

유의사항

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

· App to App 방식을 이용할 경우 {@no.3 Signature}에 서명값을 입력해야 합니다.

· 서명값은 카카오톡 App에서 앱스킴으로 받은 값이며 iOS일 경우 sig, Android일 경우 signature를 통해 받습니다. [참고] App to App 방식

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

Parameter

순번 변수명 타입 길이 필수 설명
1 ClientCode String 12 O kakaoCert에 등록된 이용기관 코드
관리자 사이트에서 확인가능
2 ReceiptID String 20 O 전자서명 요청시 반환된 접수아이디
3 Signature String - [App To App 방식 이용시 필요] 카카오톡 App에서 앱스킴으로 받은 서명값

Return

ResponseVerify

Throws

Err

A. 객체정보

A.1. Err - kakaoCert 예외 처리

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

A.2. RequestESignObj - 전자서명 요청 정보

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

A.3. ResponseESign - RequestESign 응답 정보

순번 변수명 항목명 타입 길이 설명
1 receiptId 접수아이디 String 20 전자서명 요청을 식별하기 위해 kakaoCert에서 할당한 값
2 tx_id 카카오톡 트랜잭션아이디 String - [App To App 방식 이용시 필요] 이용기관 App에서 카카오톡 App을 앱스킴 호출시 이용

A.4. ResultESignObj - 서명 상태 정보

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

A.5. ResponseVerify - VerifyESign 응답 정보

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