연동매뉴얼

Node.js API

(Express)

1. 전자서명 요청

1.1. RequestESign - 전자서명 요청

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

kakaocertService.requestESign(ClientCode, RequestESign, success, error)

유의사항

· App to App 방식을 이용할 경우 {@no.2 RequestESign}의 'isAppUseYN'에 true를 입력해야 합니다. [참고] App to App 방식

Parameter

순번 변수명 타입 길이 필수 설명
1 ClientCode string 12 O kakaoCert에 등록된 이용기관 코드
관리자 사이트에서 확인가능
2 RequestESign RequestESign - O 전자서명 요청 정보
3 success function - O 함수 호출 결과가 성공일 경우 실행하는 콜백 함수
4 error function - O 함수 호출 결과가 실패일 경우 실행하는 콜백 함수

Return

ResponseESign

Throws

Error

2. 전자서명 상태 확인

2.1. GetESignState - 서명 상태 확인

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

kakaocertService.getESignState(ClientCode, ReceiptID, success, error)

유의사항

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

Parameter

순번 변수명 타입 길이 필수 설명
1 ClientCode string 12 O kakaoCert에 등록된 이용기관 코드
관리자 사이트에서 확인가능
2 ReceiptID string 20 O 전자서명 요청시 반환된 접수아이디
3 success function - O 함수 호출 결과가 성공일 경우 실행하는 콜백 함수
4 error function - O 함수 호출 결과가 실패일 경우 실행하는 콜백 함수

Return

ResultESign

Throws

Error

3. 전자서명 검증

3.1. VerifyESign - 서명 검증 (Talk Message 방식)

· 전자서명 요청시 반환된 접수아이디를 통해 전자서명 결과를 확인합니다.

kakaocertService.verifyESign(ClientCode, ReceiptID, success, error)

유의사항

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

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

Parameter

순번 변수명 타입 길이 필수 설명
1 ClientCode string 12 O kakaoCert에 등록된 이용기관 코드
관리자 사이트에서 확인가능
2 ReceiptID string 20 O 전자서명 요청시 반환된 접수아이디
3 success function - O 함수 호출 결과가 성공일 경우 실행하는 콜백 함수
4 error function - O 함수 호출 결과가 실패일 경우 실행하는 콜백 함수

Return

VerifyResult

Throws

Error

3.2. VerifyESign - 서명 검증 (App to App 방식)

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

kakaocertService.verifyESign(ClientCode, ReceiptID, Signature, success, error)

유의사항

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

· {@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 - O [App To App 방식 이용시 필요] 카카오톡 App에서 앱스킴으로 받은 서명값
4 success function - O 함수 호출 결과가 성공일 경우 실행하는 콜백 함수
5 error function - O 함수 호출 결과가 실패일 경우 실행하는 콜백 함수

Return

VerifyResult

Throws

Error

A. 객체정보

A.1. Error - kakaoCert 에러 처리

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

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

순번 변수명 항목명 필수 타입 길이 설명
1 CallCenterNum 고객센터 전화번호 O string 20 카카오톡 인증메시지 중 "고객센터" 항목에 표시
2 Expires_in 인증요청 만료시간 O number - 최대 1000까지 입력 가능(권장 : 300), 단위 : 초(s)
└ 만료시간 안에 수신자가 미인증시, 'ResultESign' 객체의 변수 '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. ResultESign - 서명 상태 정보

순번 변수명 항목명 타입 길이 설명
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 함수 호출시 입력한 'RequestESign' 객체의 'SubClientID'에 입력한 값
└ 이 함수 호출시 값을 입력하지 않은 경우 null 반환
6 state 상태 number - 0 / 1 / 2 중 반환
└ 0 = 미확인, 1 = 서명완료, 2 = 만료
7 expires_in 인증요청 만료시간(초) number - RequestESign 함수 호출시 입력한 'RequestESign' 객체의 'Expires_in' 값
└ 만료시간 안에 수신자가 미인증시, {@no.6 state}를 2 (만료) 처리
8 callCenterNum 고객센터 전화번호 string 20 RequestESign 함수 호출시 입력한 'RequestESign' 객체의 'CallCenterNum' 값
9 tmstitle 인증요청 메시지 제목 string 40 RequestESign 함수 호출시 입력한 'RequestESign' 객체의 'TMSTitle' 값
10 tmsmessage 인증요청 메시지 부가내용 string 500 RequestESign 함수 호출시 입력한 'RequestESign' 객체의 'TMSMessage' 값
11 allowSimpleRegistYN 인증서 발급유형 선택 boolean - RequestESign 함수 호출시 입력한 'RequestESign' 객체의 'isAllowSimpleRegistYN' 값
└ true / false 중 반환
└ true = 휴대폰 본인인증만을 이용해 인증서 발급
└ false = 본인계좌 점유 인증을 이용해 인증서 발급
12 verifyNameYN 수신자 실명확인 여부 boolean - RequestESign 함수 호출시 입력한 'RequestESign' 객체의 'isVerifyNameYN' 값
└ true (확인) / false (미확인) 중 반환
└ 카카오페이가 본인인증을 통해 확보한 이용자 실명과 RequestESign 함수 호출시 입력한 'RequestESign' 객체의 '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 함수 호출시 입력한 'RequestESign' 객체의 'PayLoad' 값
20 appUseYN App to App 방식 이용 여부 boolean - RequestESign 함수 호출시 입력한 'isAppUseYN' 값
└ true (App To App 방식) / false (Talk Message 방식) 중 반환
└ 이 함수 호출시 값을 입력하지 않은 경우 false(기본값) 반환
21 tx_id 카카오톡 트랜잭션아이디 string - [App To App 방식 이용시 필요] 이용기관 App에서 카카오톡 App을 앱스킴 호출시 이용

A.5. VerifyResult - VerifyESign 응답 정보

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