이 문서는 카카오톡 인증 서비스의 K1100 본인인증 API 사용법을 안내합니다.

K1100 본인인증은 이름, 생년월일, 전화번호로 본인확인 또는 사용자를 인증하는 서비스입니다. 앱투앱(App to App) 또는 채널 메시지 방식으로 사용자에게 카카오톡에서 전자서명을 요청할 수 있으며, 전자서명에 대한 검증으로 안전하게 인증을 완료할 수 있습니다.

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

아래는 카카오톡 인증의 전자서명 과정을 표현한 시퀀스 다이어그램(Sequence Diagram)입니다.

전자서명 과정

위 과정을 요약하면 아래와 같습니다.

1. 이용기관이 인증할 사용자 정보를 전자서명 준비 API로 전달해 tx_id를 발급받습니다.
2. 이용기관이 tx_id로 전자서명 요청 API를 호출해 사용자의 인증을 요청하면, 카카오톡 앱 실행 또는 카카오톡 메시지로 사용자에게 인증 요청이 전달됩니다.
   • identify_items 파라미터에 CI를 지정해 전자서명 요청 시 서명자 정보 조회 API로 연계정보(CI)가 포함된 개인정보를 전달받아야 합니다.
3. 사용자는 카카오톡에서 전자서명으로 인증을 수행하고, 이용기관은 tx_id로 전자서명 상태 조회 API를 호출해 인증 상태를 확인합니다.
4. 전자서명 완료 확인 후, 이용기관이 tx_id로 전자서명 검증 API를 호출해 전자서명 결과 값을 전달받습니다.
5. 이용기관이 tx_id로 서명자 정보 조회 API를 호출해 서명자 정보를 전달받습니다.
   • 제공받은 연계정보(CI)가 포함된 개인정보를 이용기관 서버에서 비교해 올바른 사용자인지 검증해야 합니다.
   • 카카오톡 인증 서비스에서 제공하는 서명자 정보는 사용자 비교 또는 검증 용도 외에는 사용할 수 없습니다.

사용자는 아래와 같은 과정을 거쳐 전자서명을 수행합니다.

App to App 방식 전자서명 과정

채널 메시지 방식 전자서명 과정

카카오는 전자서명 준비 단계에서 개인 정보, CI, 또는 CI와 전화번호를 함께 사용하여 인증을 요청할 사용자를 찾습니다. 대상 사용자가 확인되지 않거나 카카오 인증서를 발급받지 않은 경우, 카카오톡 인증이 불가능하여 전자서명 준비 API 호출 시 에러가 반환됩니다. CI, 또는 CI와 전화번호를 함께 사용하는 확인 과정은 아래와 같습니다.

CI 사용 사용자 확인 과정

CI와 전화번호 사용 사용자 확인 과정

전자서명을 수행할 사용자의 정보를 카카오톡 인증 서비스에 전달하고 접수번호를 발급합니다.

이 API의 요청 결과로 받은 접수번호인 tx_id를 사용해 아래 단계의 전자서명 요청, 상태 조회, 검증을 요청할 수 있습니다.

전자서명 준비 API는 요청 URL에 경로 변수(Path variable)로 상품 코드를 포함합니다. 예를 들어 K1110 상품 이용 시, 요청 URL의 마지막 부분에 /K1110을 반드시 포함해야 합니다.

헤더(Header)에 이용기관 앱 REST API 키와 딜러사 앱 REST API 키를 담아 POST로 요청합니다. 본문에 사용자의 이름, 전화번호, 생년월일을 JSON 형식으로 포함해야 합니다. 개인정보는 반드시 지정된 키로 암호화하여 전달해야 하며, 자세한 사항은 암호화 예제를 참고합니다.

요청 성공 시 응답은 tx_id와 처리 결과인 result 값을 포함합니다. 요청 실패 시 에러 코드에서 에러 코드 정보를 확인합니다.

전자서명 준비 요청 시 사용자 개인정보인 이름, 전화번호, 생년월일과 서명할 데이터는 반드시 암호화 후 인코딩하여 전달해야 합니다. 아래 순서로 암호화와 인코딩을 처리합니다.

1. 이용기관마다 발급된 암호화 키를 사용해 평문 데이터를 AES256(CTR) 방식으로 암호화
2. 암호화한 데이터를 Base64 방식으로 인코딩(Encoding)

아래는 개인정보 암호화 및 인코딩 결과를 보여주는 예제입니다.

• 개인정보는 반드시 암호화하여 전송해야 합니다. 암호화 예제를 참고합니다.

curl -i -X POST "https://cert-sign.kakao.com/sign/v2/prepare/${PRODUCT_CODE}?settle_id=${SETTLE_ID}" \
  -H "Authorization: KakaoAK ${DEALER_REST_API_KEY}" \
  -H "Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -d '{
            "enc_version": 1,
            "phone_no": "4F8eCFmV71J9LPqNDt8TIw==",
            "name": "Mt261OQWMcbxEs28DdwQIA==",
            "birthday": "6VQXDFCe6lZFHcKzAtMfLw=="
        }'

{
  "tx_id": "027eeefd7c-2272-480d-9454-c277b28437cd"
}

전자서명 요청 API는 전자서명 준비 API로 접수된 tx_id에 해당하는 전자서명 요청을 실행합니다.

이 API의 요청 성공 결과로 사용자의 카카오톡에 전자서명 요청 또는 채널 메시지가 발송됩니다. 앱투앱 방식인 K1120 상품 이용 시, 이 API의 요청 성공 결과로 받은 scheme 값으로 카카오톡의 전자서명 요청 화면을 호출해야 합니다.

헤더(Header)에 이용기관 앱 REST API 키와 딜러사 앱 REST API 키를 담아 POST로 요청합니다. 본문에 서명 원문을 포함한 전자서명 요청 정보를 JSON 형식으로 전달해야 합니다. 상품별로 서명 원문의 데이터 형식이 지정돼 있으므로, 파라미터 설명을 참고합니다.

요청 성공 시 사용자에게 전자서명 요청이 보내지며, 응답은 tx_id와 처리 결과인 result 값을 포함합니다.

사용자는 전자서명 요청의 남은 유효시간 이내에 채널 메시지의 '인증하기' 버튼을 눌러 전자서명할 수 있습니다. 이미 전자서명을 완료했거나 유효시간이 경과한 후에는 사용자가 '인증하기' 버튼을 눌렀을 때 에러 안내가 나타납니다.

아래와 같은 경우에는 전자서명 요청이 실패할 수 있습니다.

• 사용자 전화번호에 해당하는 카카오계정 없음
  • 카카오톡 인증 서비스 이용 불가능
• 사용자 카카오계정에 본인인증 정보 없음
  • 본인인증 안내 페이지 출력
  • 사용자의 본인인증 완료 후 카카오톡 인증 서비스 이용 가능
  • 전자서명 요청 API 재호출 필요
• 사용자 정보가 카카오계정의 본인인증 정보와 일치하지 않음
  • 카카오톡 인증 서비스 이용 불가능
• 사용자 정보에 계약 시 협의되지 않은 값이 있음
  • 카카오톡 인증 서비스 이용 불가능

요청 실패 시 에러 코드에서 에러 코드 정보를 확인합니다.

전자서명 요청의 파라미터 값은 사용자 인증 요청 안내문에 사용됩니다. 아래 예시와 설명을 참고합니다.

사용자 인증 요청 안내문 구성 예시

curl -i -X POST "https://cert-sign.kakao.com/sign/v2/request?settle_id=${SETTLE_ID}" \
  -H "Authorization: KakaoAK ${DEALER_REST_API_KEY}" \
  -H "Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -d '{
            "return_url": "https://www.sample.com/return_url",
            "expires_in": 1200,
            "data": "{\"txId\": \"027eeefd7c-2272-480d-9454-c277b28437cd\",\"data\": \"서명원문\"}",
            "identify_items": ["CI", "NAME", "BIRTHDAY", "PHONE_NUMBER", "GENDER". "NATIONALITY", "MOBILE_CARRIER"],
            "delegate_info": {
                "request_type": "본인인증",
                "receiver_name": "ajNZRTQ1ait0ZytD" // 암호화 필수
            }
        }'

{
  "tx_id": "027eeefd7c-2272-480d-9454-c277b28437cd",
  "result": "Y"
}

{
  "tx_id": "027eeefd7c-2272-480d-9454-c277b28437cd",
  "result": "Y",
  "scheme": "kakaotalk://..."
}

전자서명 상태 조회 API는 카카오톡 인증(K1100) 상품으로 요청한 전자서명의 상태를 확인합니다.

사용자는 카카오톡으로 인증을 수행하므로, 이용기관은 전자서명 상태 조회 API로만 인증 상태를 확인할 수 있습니다.

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

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

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

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

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

요청 실패 시 에러 코드에서 에러 코드 정보를 확인합니다.

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": "REQUESTED",
  "tx_id": "027eeefd7c-2272-480d-9454-c277b28437cd",
  "created_at": "2021-06-18 13:53:36",
  "viewed_at": null,
  "completed_at": null,
  "expired_at": "2021-06-18 14:03:36",
  "partner_notified_at": null
}

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

이 API는 카카오톡 인증(K1100)과 카카오톡 인증 로그인(K2100)의 전자서명에 대한 검증을 모두 지원합니다.

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

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

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

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

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

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}" // 상단 설명 및 표 참고
  }
}

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

아래는 실제 서비스에서 고려해야 할 여러 요소(성능, 예외 처리, 동시성 등)가 반영되지 않은 참고용 예제입니다.

class VerifySample {

    val kakaoClient = HttpClient.newBuilder().build()
    val mapper = ObjectMapper()
    val settleId = "PARTNER_SETTLE_ID"
    private val transformation = "AES/CTR/NoPadding"
    private val secretKeySpec = SecretKeySpec("PARTNER_SECRET_KEY".decodeBase64(), "AES")
    private val ivSpec = IvParameterSpec("PARTNER_IV".decodeBase64())

    private fun decrypt(content: ByteArray): String =
        Cipher.getInstance(transformation).run {
            init(Cipher.DECRYPT_MODE, secretKeySpec, ivSpec)
            String(doFinal(content))
        }

    private fun createHttpRequest(uri: URI): HttpRequest {
        return HttpRequest.newBuilder()
            .uri(uri)
            .setHeader(AUTHORIZATION, DEALER_REST_API_KEY)
            .setHeader(TARGET_AUTHORIZATION, PARTNER_REST_API_KEY)
            .GET()
            .build()
    }

    // 전자서명 검증 API
    private fun callVerify(txId: String): VerifyResponse {
        val uri = URI.create(createURI(txId))
        val response: HttpResponse<String> = kakaoClient.send(createHttpRequest(uri), HttpResponse.BodyHandlers.ofString())
        return mapper.readValue<VerifyResponse>(response.body())
    }

    private fun createURI(txId: String): String {
        val sb = StringBuilder()
        sb.append("https://cert-sign.kakao.com/sign/v2/verify?settle_id=")
            .append(settleId)
            .append("&tx_id=")
            .append(txId)
        return sb.toString()
    }

    /**
     * 이용기관에서 CI를 보유한 경우
     * 전자서명 검증 API를 호출하여 보유한 CI와 비교
     * !!중요!! 전자서명 검증 API 호출 및 CI 비교는 반드시 서버에서 수행
     */
    // 전자서명 검증 API 호출
    fun compareCI(txId: String): Boolean {
        // 응답에 포함된 CI를 복호화
        val encryptedCi = callVerify(txId).ci
        // 이용기관에서 보유한 CI와 비교
        val decryptedCI = decrypt(encryptedCi.decodeBase64())
        return exist(decryptedCI)
    }

    /**
     * 실명인증된 CI가 있는 경우
     * 전자서명 검증 API의 결과와 실명인증된 CI를 비교
     * !!중요!! 전자서명 검증 API 호출 및 CI 비교는 반드시 서버에서 수행
     */
    // 전자서명 검증 API 호출
    fun compareCI(txId: String, ci: String): Boolean {
        // 응답에 포함된 CI를 복호화
        val encryptedCi = callVerify(txId).ci
        // 실명인증된 CI와 비교
        val decryptedCI = decrypt(encryptedCi.decodeBase64())
        return ci == decryptedCI
    }
}

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

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

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

요청 성공 시 응답은 전자서명 요청의 identify_items 파라미터로 지정한 서명자 정보를 포함합니다. 요청 실패 시 에러 코드에서 에러 코드 정보를 확인합니다.

• 전자서명 요청의 identify_items 파라미터로 지정한 서명자 정보만 응답에 포함

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}",
  "nationality": "${NATIONALITY}",
  "mobile_carrier": "${MOBILE_CARRIER}",
  "ci": "${CI}",
  "vid": "${VID}"
}

• 이해하기
• 에러 코드
• 디자인 가이드