연동매뉴얼

PHP API

(PHP / Laravel)

Index

1. 자동이체 출금동의 요청

2. 자동이체 출금동의 상태 확인

3. 자동이체 출금동의 검증

A. 객체정보

1. 자동이체 출금동의 요청

자동이체 출금동의 API 주의사항

  • 해당 서비스는 전자서명을 하는 카카오톡 이용자와 출금계좌의 예금주가 동일한 경우에만 이용이 가능합니다.
  • 전자서명 당사자와 출금계좌의 예금주가 동일인임을 체크하는 의무는 이용기관에 있습니다.
  • 금융결제원에 증빙자료 제출은 이용기관 측에서 진행해야 합니다.
  • 증빙자료는 [3.1. VerifyCMS] 함수 호출로 반환 받은 VerifyResult 객체의 변수 'signedData' 값을 base64url 방식으로 디코딩하여 binary 형식으로 구성된 der 확장자 파일을 제출합니다.

1.1. RequestCMS - 자동이체 출금동의 요청

· 카카오톡 이용자에게 자동이체 출금동의를 요청합니다.

public function requestCMS($ClientCode, $RequestCMS, $appUseYN = false)

Parameter

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

Return

ResponseCMS

Throws

KakaocertException

2. 자동이체 출금동의 상태 확인

2.1. GetCMSState - 서명 상태 확인

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

public function getCMSState($ClientCode, $receiptID)

유의사항

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

Parameter

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

Return

ResultCMS

Throws

KakaocertException

3. 자동이체 출금동의 검증

3.1. VerifyCMS - 서명 검증

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

· 금융결제원에 증빙자료 제출시, 전자서명 데이터 전문('signedData')를 base64url 방식으로 디코딩하여 binary 형식으로 구성된 der 확장자 파일을 제출합니다.

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

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

public function verifyCMS($ClientCode, $receiptID, $signature = null)

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

· App to App 방식을 이용할 경우 {@no.3 Signature}에 카카오톡 App에서 앱스킴으로 받은 서명값을 입력해야 하며, iOS일 경우 sig, Android일 경우 signature를 통해 받습니다. [참고] App to App 방식

Parameter

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

Return

VerifyResult

Throws

KakaocertException

A. 객체정보

A.1. KakaocertException - kakaoCert 예외 처리

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

A.2. RequestCMS - 자동이체 출금동의 요청 정보

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

A.3. ResponseCMS - RequestCMS 응답 정보

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

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

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

A.5. VerifyResult - VerifyCMS 응답 정보

순번 변수명 항목명 타입 길이 설명
1 receiptId 접수아이디 String 20 자동이체 출금동의 요청을 식별하기 위해 kakaoCert에서 할당한 값
2 signedData 전자서명 데이터 전문 String 4096 금융결제원에 증빙자료 제출시 base64url 방식으로 디코딩하여 binary 형식으로 구성된 der 확장자 파일을 제출