페이지 이동경로

문서>
카카오톡 인증 서비스>
K1400: 인증 표준창

카카오톡 인증 서비스

K1400: 인증 표준창

이 문서는 카카오톡 인증 서비스의 K1400 인증 표준창 API 사용법을 안내합니다.

시작하기 전에

기능 소개

K1400 인증 표준창은 카카오에서 이용기관에 제공하는 인증 웹 페이지로 Kakao SDK for JavaScript(이하 JavaScript SDK)로 제공합니다. 카카오톡 클라이언트 11.2.0 이상 버전, JavaScript SDK 2.7.4 이상 버전, PC나 태블릿 웹 브라우저 환경에서 사용할 수 있습니다.

사용자는 정보(이름, 생년월일, 전화번호)를 직접 입력하는 휴대폰 인증 또는 QR 코드 스캔 후 2차 인증 문자를 선택하는 QR 인증 방식 중 하나를 선택해 인증 후 전자서명할 수 있습니다. 각 인증 방식에 대한 자세한 내용은 사용자 인증 과정을 참고합니다.

이용기관은 전자서명 상태 확인하기와 전자서명 검증하기로 전자서명 상태를 확인 및 검증하고, 서명자 정보 가져오기로 사용자를 식별 및 검증할 수 있는 서명자 정보를 제공받을 수 있습니다.

카카오톡 인증 서비스 API는 서버간 연동(Server to Server)을 원칙으로 합니다.

JavaScript SDK 설치

K1400 인증 표준창은 Kakao SDK for JavaScript(이하 JavaScript SDK)로 제공합니다. 아래 순서로 Kakao SDK for JavaScript(이하 JavaScript SDK)의 설정, 설치, 초기화를 완료합니다.

플랫폼 등록
설치
- JavaScript SDK 2.7.4 이상 버전에서 사용 가능
초기화

인증 표준창 전자서명 과정

인증 표준창의 전자서명 과정에 대해 설명합니다. 아래 시퀀스 다이어그램(Sequence Diagram)과 설명을 참고합니다.

사용자가 PC 또는 태블릿 웹 브라우저 환경의 이용기관 서비스에서 인증을 요청합니다.
이용기관이 인증 표준창 호출하기를 요청합니다.
사용자는 인증 표준창에서 휴대폰 인증과 QR 인증 중 원하는 방식을 선택해 인증 후 전자서명을 수행합니다. 사용자인증 방식에 대한 자세한 내용은 사용자 인증 과정을 참고합니다.
사용자 전자서명 완료 후 인증 표준창은 결과에 따라 아래 쿼리 파라미터를 포함한 Redirect URI로 리다이렉트(HTTP 302)됩니다.
- 전자서명 성공 시: tx_id(전자서명 접수번호)
- 전자서명 실패 시: error_code(카카오톡 인증 표준창 에러 코드)
이용기관은 필요에 따라 tx_id로 전자서명 상태 확인하기 API를 호출해 상태를 확인할 수 있습니다. (선택)
이용기관 서버에서 tx_id로 전자서명 검증하기 API를 호출해 전자서명 결과 값을 전달받습니다.
이용기관 서버에서 tx_id로 서명자 정보 가져오기 API를 호출해 서명자 정보를 전달받습니다.
- 카카오톡 인증 서비스에서 제공하는 서명자 정보는 사용자 비교 또는 검증 용도 외에는 사용할 수 없습니다.

사용자 인증 과정

인증 표준창의 사용자 인증 과정에 대해 안내합니다. 사용자 인증 중 QR 인증 기능은 카카오톡 클라이언트 11.2.0 이상 버전에서 사용할 수 있습니다. 아래 각 항목의 이미지와 설명을 확인합니다.

인증 표준창에서 사용자가 [휴대폰인증] 탭을 선택하면, 사용자 정보(이름, 생년월일, 휴대폰번호) 입력 항목을 표시합니다.
사용자가 정보를 입력하고 개인정보 수집 및 이용 동의 후 [인증 요청]을 선택하면, 인증 표준창은 인증 대기화면으로 전환되고 사용자의 카카오톡으로 전자서명 요청 메시지(채널 메시지)를 보냅니다.
사용자는 수신한 메시지의 [인증하기]를 선택하고 전자서명할 수 있습니다. 만약 발급받은 인증서가 없으면 인증서 발급 절차가 시작됩니다.
전자서명 완료 시 인증 표준창은 결과에 따라 응답을 포함한 Redirect URI로 리다이렉트(HTTP 302)되고, 사용자의 카카오톡으로 인증 완료 메시지를 전달합니다.

인증 표준창에서 사용자가 [QR 인증] 탭을 선택하면, QR 코드와 2차 인증 문자(영문 2글자)를 표시합니다.
사용자가 휴대폰의 카메라로 표시된 QR 코드를 스캔하면, 사용자의 카카오톡에 2차 인증 문자 입력창이 표시됩니다.
사용자가 QR 코드와 함께 표시된 2차 인증 문자를 선택하고 전자서명할 수 있습니다. 만약 발급받은 인증서가 없으면 인증서 발급 절차가 시작됩니다.
인증 완료 시 인증 표준창은 결과에 따라 응답을 포함한 Redirect URI로 리다이렉트(HTTP 302)되고, 사용자의 카카오톡으로 인증 완료 메시지를 전달합니다.

인증 표준창 호출하기

인증 표준창 호출하기는 휴대폰 인증 또는 QR 인증할 수 있는 웹 페이지를 열어 사용자에게 인증을 요청하는 API입니다.

JavaScript SDK 설치 후 Kakao.Cert.identify()로 인증 표준창을 호출합니다. 필수 파라미터를 요청에 포함해야 합니다.

인증 표준창 호출 및 전자서명 완료 후 서명자 정보 가져오기로 응답받을 서명자 정보를 identifyItems에 지정해야 합니다. 필요한 경우 tabs로 휴대폰 인증과 QR 인증 탭의 순서 를 정할 수 있습니다.

요청 성공 시 사용자에게 인증 표준창을 표시하고 사용자가 선택한 인증 방식에 따라 사용자 인증 과정을 수행합니다. 사용자 인증이 완료되면 인증 표준창은 tx_id를 포함한 redirectUri로 리다이렉트(HTTP 302)됩니다.

요청 실패 시 문제 해결의 카카오톡 인증 표준창 에러 코드 정보를 확인합니다.

요청

파라미터

이름	타입	설명	필수
redirectUri	`String`	요청 처리 결과를 전달받을 Redirect URI	O
dealerAppKey	`String`	딜러사 앱의 JavaScript 키	O
settleId	`String`	정산 ID, `isTest`가 `true`인 경우 테스트용 정산 ID로 포함 필요, ID 종류 참고	O
identifyItems	`String`	서명자 정보 가져오기 응답으로 확인할 서명자 정보 목록 아래 중 하나 이상의 값을 포함해 쉼표로 구분된 문자열로 전달(예: `"name,birthday"`) `ci`: 연계정보 `name`: 이름 `birthday`: 생일 `phone_number`: 전화번호 `gender`: 성별	O
tabs	`String`	인증 표준창 탭의 정렬 순서 목록, 아래 값을 모두 포함해 쉼표로 구분된 문자열로 전달(기본값: `"phone_number,qr"`) `phone_number`: 휴대폰 인증 `qr`: QR 인증	X
isTest	`Boolean`	인증 표준창의 테스트 호출 여부(기본값: `false`)	X

응답

인증 표준창 호출하기는 응답을 결과별 아래 쿼리 파라미터를 포함해 redirectUri에 GET 요청으로 리다이렉트(HTTP 302)합니다.

쿼리 파라미터

이름	타입	설명
tx_id	`String`	전자서명 접수번호 전자서명 성공 시 응답에 포함
error_code	`String`	에러 코드 전자서명 실패 시 응답에 포함

예제

요청

Kakao.Cert.identify({
    redirectUri: "${REDIRECT_URI}",
    dealerAppKey: "${DEALER_APP_JAVASCRIPT_KEY}",
    settleId: "${SETTLE_ID}",
    isTest: true,
    tabs: "qr,phone_number",
    identifyItems: "name,birthday,ci",
})

전자서명 상태 확인하기

기본 정보

메서드	URL	인증 방식
`GET`	`https://cert-sign.kakao.com/sign/v2/status`	REST API 키

권한	사전 설정	카카오 로그인	동의항목
필요	-	-	-

전자서명 상태 확인하기 API는 인증 표준창(K1400) 상품으로 요청한 전자서명의 상태를 확인합니다. 사용자가 카카오톡으로 인증을 수행하기 때문에, 이용기관은 전자서명 상태 확인하기 API로만 인증 상태를 확인할 수 있습니다.

헤더(Header)에 이용기관 앱 REST API 키와 딜러사 앱 REST API 키를 담아 GET으로 요청합니다. 본문에 상태를 확인할 전자서명 요청의 tx_id와 정산 ID를 포함해야 합니다.

요청 성공 시 응답은 전자서명의 상태를 포함합니다. 전자서명의 상태는 요청(REQUESTED), 완료(COMPLETED), 만료(EXPIRED) 세 가지로 각각 다음과 같이 조치합니다.

요청
- 사용자에게 전자서명 요청이 전달된 상태
- 사용자가 전자서명 요청을 정상적으로 확인했다면 viewed_at 필드 값으로 확인 가능
- 전자서명 상태가 완료 또는 만료로 확인될 때까지 주기적으로 전자서명 확인하기 API 재요청
완료
- 사용자가 전자서명을 완료한 상태
- 전자서명 검증하기 API를 사용해 결과 값 요청
만료
- 전자서명 요청이 만료된 상태
- 인증 실패 처리, 또는 전자서명 요청하기 API를 사용해 다시 사용자에게 전자서명 요청

전자서명이 완료된 경우에는 사용자가 서명한 일시, 전자서명이 만료되는 일시를 비롯한 시간 정보들을 제공합니다. 이미 이용기관이 전자서명 검증하기 API를 요청해 전자서명 결과 값을 전달받았다면, 전자서명 결과 값이 전달된 일시 정보를 제공합니다.

사용자의 인증서 상태에 따라 인증서를 발급 또는 재발급하거나 2차 본인인증(은행 계좌 확인)을 해야 할 수 있습니다. 이 경우, 추가 인증까지 모두 완료된 후 전자서명 상태가 완료로 변경됩니다.

요청 실패 시 문제 해결의 카카오톡 인증 에러 코드 정보를 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DEALER_REST_API_KEY}` 인증 방식, 딜러사 앱의 REST API 키로 인증 요청	O
Target-Authorization	`Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}` 인증 방식, 이용기관 앱 REST API 키로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
settle_id	`String`	정산 ID	O
tx_id	`String`	전자서명 원문 접수번호	O

응답

본문

이름	타입	설명
tx_id	`String`	전자서명 원문 접수번호
status	`String`	전자서명 상태, 다음 중 하나 `REQUESTED`: 사용자에게 전자서명을 요청함, 사용자는 채널 메시지를 통해 전자서명 요청을 받음 `COMPLETED`: 사용자가 전자서명을 완료함 `EXPIRED`: 유효시간 이내에 사용자가 전자서명을 완료하지 않아 요청이 만료됨
created_at	`String`	전자서명 요청 일시*
viewed_at	`String`	사용자가 전자서명 요청을 확인한 일시*
completed_at	`String`	사용자가 전자서명을 완료한 일시*
expired_at	`String`	전자서명 만료 일시*
partner_notified_at	`String`	이용기관이 전자서명 검증하기 API를 통해 전자서명 결과 값을 전달받은 일시*

* 시간은 yyyy-MM-dd'T'HH:mm:ss 형식, RFC3339 참고

예제

요청

curl -i -X GET "https://cert-sign.kakao.com/sign/v2/status?settle_id=${SETTLE_ID}&tx_id=${TX_ID}" \
    -H "Authorization: KakaoAK ${DEALER_REST_API_KEY}" \
    -H "Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}" \
    -H "Content-Type: application/json;charset=UTF-8"

응답

{
    "status": "COMPLETED",
    "tx_id": "${TX_ID}",
    "created_at": "2024-10-28T12:51:31",
    "viewed_at": "2024-10-28T12:51:35",
    "completed_at": "2024-10-28T12:51:41",
    "expired_at": "2024-10-28T13:01:21",
    "partner_notified_at": null
}

전자서명 검증하기

기본 정보

메서드	URL	인증 방식
`GET`	`https://cert-sign.kakao.com/sign/v2/verify`	REST API 키

권한	사전 설정	카카오 로그인	동의항목
필요	-	-	-

전자서명 검증하기 API는 완료된 전자서명을 검증하고 이용기관에 전자서명 데이터 전문을 제공합니다.

이 API는 완료된 전자서명 요청당 1회만 요청 가능하며, 사용자가 서명을 완료한 후, 일정시간(10분) 동안만 정상 응답합니다. 이후 요청에 대해서는 E2017 에러가 발생합니다.

헤더(Header)에 이용기관 앱 REST API 키와 딜러사 앱 REST API 키를 담아 GET으로 요청합니다. 본문에 완료된 전자서명 요청의 tx_id와 정산 ID를 포함해야 합니다.

요청 성공 시 응답은 전자서명의 상태와 전자서명 검증 결과를 포함합니다. 요청 실패 시 문제 해결의 카카오톡 인증 에러 코드 정보를 확인합니다.

전자서명 검증하기 응답 구성은 상품별로 다르므로 다음 표를 참고합니다.

상품	기본 검증 값	`data` 필드 구성
`K1410`, `K1430`	카카오 내부적으로 생성된 임의의 난수값	`result`, `request_token`

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DEALER_REST_API_KEY}` 인증 방식, 딜러사 앱의 REST API 키로 인증 요청	O
Target-Authorization	`Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}` 인증 방식, 이용기관 앱 REST API 키로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
settle_id	`String`	정산 ID	O
tx_id	`String`	전자서명 원문 접수번호	O

응답

본문

이름	타입	설명
status	`String`	전자서명 상태, 전자서명 검증 시에는 전자서명이 완료된 상태인 `COMPLETE` 값만 제공되며, 이 외 상태인 경우 에러 응답
data	`JSON`	전자서명 검증 결과 아래 data: 전자서명 검증 결과 표 참고

data: 전자서명 검증 결과

상단 설명의 응답 구성 표를 함께 참고합니다.

이름	타입	설명
result	`String`	전자서명 검증 결과 `Y`: 검증 성공 `N`: 실패
request_token	`String`	카카오 인증 서버에서 생성된 사용자 인증용 임의의 난수, 이용기관에서 처리 불필요

예제

요청

curl -i -X GET "https://cert-sign.kakao.com/sign/v2/verify?settle_id=${SETTLE_ID}&tx_id=${TX_ID}" \
    -H "Authorization: KakaoAK ${DEALER_REST_API_KEY}" \
    -H "Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}" \
    -H "Content-Type: application/json;charset=UTF-8"

응답

{
    "status": "COMPLETED",
    "data": {
        "result": "Y",
        "request_token": "${DATA}"    // 상단 설명 및 표 참고
    }
}

서명자 정보 가져오기

기본 정보

메서드	URL	인증 방식
`GET`	`https://cert-sign.kakao.com/sign/v2/identify`	REST API 키

권한	사전 설정	카카오 로그인	동의항목
필요	-	-	-

서명자 정보받기 API는 서명을 완료한 서명자 정보를 제공합니다.

이 API는 전자서명 검증하기 호출 후 요청 가능하며, 사용자 서명 완료 후 일정시간(10분)동안 1회만 요청 가능합니다. 이후 요청에 대해서는 E2017 에러가 발생합니다. 서명자의 개인정보 제공 동의 및 서명 완료 후, 개발 설계 오류, 네트워크 오류 등으로 인한 이용기관의 정보 수신 실패에 대해 카카오는 책임을 지지 않습니다.

요청 성공 시 응답은 인증 표준창 호출하기 요청의 identifyItems로 지정한 서명자 정보를 포함합니다. 문제 해결의 카카오톡 인증 에러 코드 정보를 확인합니다.

주의

카카오톡 인증 서비스에서 제공하는 연계정보(CI)와 이름, 생년월일, 전화번호는 사용자 비교 및 검증 용도로만 사용할 수 있습니다. 서명자 정보 가져오기 API를 통해 제공받은 CI, 이름, 생년월일, 전화번호를 이용기관의 정보와 비교해 올바른 사용자인지 검증해야 합니다. 비교 및 검증은 반드시 이용기관 서버에서 수행해야 합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DEALER_REST_API_KEY}` 인증 방식, 딜러사 앱의 REST API 키로 인증 요청	O
Target-Authorization	`Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}` 인증 방식, 이용기관 앱 REST API 키로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
settle_id	`String`	정산 ID	O
tx_id	`String`	전자서명 원문 접수번호	O

응답

본문

인증 표준창 호출하기 요청의 identifyItems로 지정한 서명자 정보만 응답에 포함

이름	타입	설명
name	`String`	암호화된 서명자의 이름
phone_no	`String`	암호화된 서명자의 카카오톡 전화번호
birthday	`String`	암호화된 서명자의 생년월일
gender	`String`	암호화된 서명자의 성별
ci	`String`	암호화된 서명자의 CI(연계정보)
vid	`String`	암호화된 서명자의 CI 검증값, K1400 상품은 CI 검증값을 제공하지 않아 `null`로 고정

예제

요청

curl -i -X GET "https://cert-sign.kakao.com/sign/v2/identify?settle_id=${SETTLE_ID}&tx_id=${TX_ID}" \
    -H "Authorization: KakaoAK ${DEALER_REST_API_KEY}" \
    -H "Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}" \
    -H "Content-Type: application/json;charset=UTF-8"

응답

{
    "name": "${NAME}",
    "phone_no": "${PHONE_NO}",
    "birthday": "${BIRTHDAY}",
    "gender": "${GENDER}",
}

menu

시작하기

로그인

커뮤니케이션

지도/로컬

내비게이션

광고

검색

더 보기

카카오톡 인증 서비스

K1400: 인증 표준창

시작하기 전에

기능 소개

JavaScript SDK 설치

인증 표준창 전자서명 과정

사용자 인증 과정

인증 표준창 호출하기

요청

파라미터

응답

쿼리 파라미터

예제

요청

전자서명 상태 확인하기

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

예제

요청

응답

전자서명 검증하기

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

data: 전자서명 검증 결과

예제

요청

응답

서명자 정보 가져오기

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

예제

요청

응답

더 보기