K3500: 전자서명

이 문서는 카카오톡 인증 서비스의 K3500 전자서명 API 사용법을 안내합니다.

시작하기 전에

K3500 전자서명은 계약 또는 문서에 전자서명하는 서비스입니다. 이름, 생년월일, 전화번호, 사용자 연계정보(CI)를 활용하여 서명할 사용자를 특정합니다.

서명 요청 방식은 사용자가 카카오톡 앱을 실행시키고 서명하는 앱투앱(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)가 포함된 개인정보를 이용기관 서버에서 비교해 올바른 사용자인지 검증해야 합니다.
   • 카카오톡 인증 서비스에서 제공하는 서명자 정보는 사용자 비교 또는 검증 용도 외에는 사용할 수 없습니다.

사용자 인증 과정

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

사용자는 아래와 같이 전자서명할 원문을 확인하고 서명할 수 있습니다. document_type이 TEXT인 경우에는 전문을 확인할 수 있는 페이지를 제공합니다.

전자서명 준비하기

기본 정보

전자서명 준비하기 API는 전자서명을 수행할 사용자의 정보를 카카오톡 인증 서비스에 전달하고 접수번호를 발급합니다. 이 API의 요청 결과로 받은 tx_id를 사용해 다음 단계의 전자서명 요청하기, 상태 확인하기, 검증하기를 요청할 수 있습니다. 다건서명(K3511, K3521)의 경우 document_tx_ids도 포함해야 합니다.

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

헤더(Header)에 이용기관 앱 REST API 키와 딜러사 앱 REST API 키를 담아 POST로 요청합니다. 본문의 type에 사용자 인증 방식을 입력하고, 하단에 각 인증 방식에 따라 필요한 사용자의 이름, 전화번호, 생년월일, CI를 JSON 형식으로 포함해야 합니다. 개인정보는 반드시 지정된 키로 암호화하여 전달해야 하며, 자세한 사항은 암호화 예제를 참고합니다. 다건서명의 경우 count에 전자서명을 요청할 원문 갯수를 입력합니다.

요청 성공 시 응답은 tx_id를 포함합니다. 요청 실패 시 문제 해결에서 에러 코드 정보를 확인합니다.

암호화 예제

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

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

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

요청

헤더

경로 변수

쿼리 파라미터

본문

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

응답

본문

예제

요청: 단건서명(K3510, K3520)

curl -i -X POST "https://cert-sign.kakao.com/sign/doc/v1/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,
            "type": "CI",
            "ci": "WkrAtLgnmEoN2mbDqqZQfAlMagiWyQ4Zn+VjuGxKeg/6F3zIGQueEMkeSqaJHSUpaZycTXSf+gnqL2z44t2mlWiFdEYy8/3UiPSEiHoKSE6fTbhvr5cf1g=="
        }'

요청: 다건서명(K3511, K3521)

curl -i -X POST "https://cert-sign.kakao.com/sign/doc/v1/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,
            "type": "CI",
            "ci": "WkrAtLgnmEoN2mbDqqZQfAlMagiWyQ4Zn+VjuGxKeg/6F3zIGQueEMkeSqaJHSUpaZycTXSf+gnqL2z44t2mlWiFdEYy8/3UiPSEiHoKSE6fTbhvr5cf1g==",
            "count": 20
        }'

응답: 단건서명(K3510, K3520)

{
    "tx_id": "02a05c5bfe-d89a-448b-a538-d80dc5b038fa"
}

응답: 다건서명(K3511, K3521)

{
    "tx_id": "02a05c5bfe-d89a-448b-a538-d80dc5b038fa",
    "document_tx_ids": [
        "0297e72d72-7e09-4d94-b3f0-1d2eff325ab7",
        "02bbe332fd-7f02-4633-991c-0d91037e592e",
        "024778616f-3bd1-4201-b0ed-239eab1a86f4",
        "02aaeaa7e4-c8d7-46c8-86f2-c4cb7f806c34",
        "0228d38333-079e-4b8c-aaca-10445525ac30",
        "0230bb3d41-9c13-4bef-9113-c2298e478f89",
        "02cbffbc9a-e8b2-4f03-b06f-e8943b776de2",
        "029a87e896-d778-4597-b689-e6ff99ed9d86",
        "02a8834830-9be9-4dd8-bc75-161d5924654b",
        "02216d11cc-f774-437a-b655-92f0b98ff0b7",
        "027eeefd7c-2272-480d-9454-c277b28437cd",
        "02a9375581-d2f4-40a9-ab7a-894b12e887f5",
        "02badeb5e1-c34a-4ff9-a845-5175ac724ec6",
        "02a05331fe-bcbc-4798-9980-de60bb5c03d5",
        "02d656178a-8825-4aee-9d11-72cd9f16ec3d",
        "02b014a10f-6dee-421f-b094-534e62c2f632",
        "0271980626-f5cc-4823-922a-131d5b4fb1c1",
        "02e9604452-bc82-4d5e-a3c6-38fc91c8fcc7",
        "0233c6866c-435c-42a1-8902-3ed1486abfa1",
        "02af5a8d26-c51d-48bb-ab58-91907b4cab2d"
    ]
}

전자서명 요청하기

기본 정보

전자서명 요청하기 API는 전자서명 준비하기 API를 통해 접수된 tx_id에 해당하는 전자서명 요청을 실행합니다. 이 API의 요청 성공 결과로 사용자의 카카오톡에 전자서명 요청 또는 채널 메시지가 발송됩니다. 앱투앱 방식(K3520, K3521) 상품 이용 시, 이 API의 요청 성공 결과로 받은 scheme으로 카카오톡의 전자서명 요청 화면을 호출해야 합니다.

헤더(Header)에 이용기관 앱 REST API 키와 딜러사 앱 REST API 키를 담아 POST로 요청합니다. 본문에 서명 원문을 포함한 전자서명 요청 정보를 JSON 형식으로 전달해야 합니다. 서명 원문은 단건서명(K3510, K3520)의 경우 document에 JSON 형식으로, 다건서명(K3511, K3521)의 경우 documents에 JSON 형식의 배열로 입력해야 합니다.

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

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

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

• 사용자 전화번호에 해당하는 카카오계정 없음
  • 카카오톡 인증 서비스 이용 불가능
• 사용자 카카오계정에 본인인증 정보 없음
  • 본인인증 안내 페이지 출력
  • 사용자의 본인인증 완료 후 카카오톡 인증 서비스 이용 가능
  • 전자서명 요청하기 API 재호출 필요
• 사용자 정보가 카카오계정의 본인인증 정보와 일치하지 않음
  • 카카오톡 인증 서비스 이용 불가능
• 사용자 정보에 계약 시 협의되지 않은 값이 있음
  • 카카오톡 인증 서비스 이용 불가능
• ci에 해당하는 카카오계정 없음
• ci에 해당하는 카카오계정이 2개 이상이고, 그 중 유효한 인증서를 발급받은 카카오계정 없음

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

사용자 인증 요청 안내문

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

documents 목록 주의사항

documents 목록은 전자서명 준비하기 API의 요청 성공 결과로 받은 document_tx_ids와 동일한 순서여야 합니다. 해당 목록의 값 중 하나인 document의 각 항목은 JSON 내부의 문자열(String)을 올바르게 해석(Parsing)할 수 있도록 역슬래시(\) 문자를 큰따옴표(") 앞에 표기해야 합니다. (예: "document": "{\"txId\": ...) 파라미터 안내와 요청 예제를 참고합니다.

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

요청

헤더

쿼리 파라미터

본문

• 상품 종류별 필수 파라미터
  • 단건서명(K3510, K3520): document_title, document
  • 다건서명(K3511, K3521): documents

* sign_type, hash_type 파라미터와 document_type의 PLAIN_HASH 값은 카카오톡 10.4.5 버전 이상에서만 사용 가능

Document

delegate_info: 사용자 인증 요청 안내문

• 상품 종류별 필수 파라미터
  • 다건서명(K3511, K3521): request_type

* call_center_number, call_center_name, request_organization: Deprecated, 등록된 이용기관 정보를 사용하도록 변경

응답

본문

예제

요청: document_type이 TEXT인 단건서명(K3510, K3520)

curl -i -X POST "https://cert-sign.kakao.com/sign/doc/v1/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 '{
            "tx_id": "02a05c5bfe-d89a-448b-a538-d80dc5b038fa",
            "return_url": "https://www.sample.com/return_url",
            "expires_in": 1200,
            "document_type": "TEXT",
            "delegate_info": {
                "receiver_name": "ajNZRTQ1ait0ZytD" // 암호화 필수
            },
            "document_title": "카카오뱅크 거래내역",
            "document": "{\"txId\": \"0297e72d72-7e09-4d94-b3f0-1d2eff325ab7\",\"data\": \"{\\\"납부자 출금은행\\\":\\\"카카오뱅크\\\",\\\"납부자 출금계좌번호\\\":\\\"111111-11-111111\\\",\\\"출금 계좌주명\\\":\\\"홍길동\\\"}\"}"
        }'

요청: document_type이 TEXT인 다건서명(K3511, K3521)

curl -i -X POST "https://cert-sign.kakao.com/sign/doc/v1/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 '{
            "tx_id": "02a05c5bfe-d89a-448b-a538-d80dc5b038fa",
            "return_url": "https://www.sample.com/return_url",
            "expires_in": 1200,
            "identify_items": ["CI", "NAME", "BIRTHDAY", "PHONE_NUMBER", "GENDER"],
            "document_type": "TEXT",
            "delegate_info": {
                "request_type": "전자계약",
                "receiver_name": "ajNZRTQ1ait0ZytD" // 암호화 필수
            },
            "documents": [
                {
                    "document_tx_id": "0297e72d72-7e09-4d94-b3f0-1d2eff325ab7",
                    "document_title": "카카오뱅크 거래내역",
                    "document": "{\"txId\": \"0297e72d72-7e09-4d94-b3f0-1d2eff325ab7\",\"data\": \"{\\\"납부자 출금은행\\\":\\\"카카오뱅크\\\",\\\"납부자 출금계좌번호\\\":\\\"111111-11-111111\\\",\\\"출금 계좌주명\\\":\\\"홍길동\\\"}\"}"
                },
                ...
            ]
        }'

요청: document_type이 HASH인 단건서명(K3510, K3520)

curl -i -X POST "https://cert-sign.kakao.com/sign/doc/v1/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 '{
            "tx_id": "02a05c5bfe-d89a-448b-a538-d80dc5b038fa",
            "return_url": "https://www.sample.com/return_url",
            "expires_in": 1200,
            "identify_items": ["CI", "NAME", "BIRTHDAY", "PHONE_NUMBER", "GENDER"],
            "document_type": "HASH",
            "delegate_info": {
                "receiver_name": "ajNZRTQ1ait0ZytD" // 암호화 필수
            },
            "document_title": "카카오뱅크 거래내역",
            "document": "{\"txId\": \"0297e72d72-7e09-4d94-b3f0-1d2eff325ab7\",\"data\": \"715cfad410498ece9eea5f9f6d963904cf62341d74379c3dcd76e01e37e6a621\"}"
        }'

요청: document_type이 HASH인 다건서명(K3511, K3521)

curl -i -X POST "https://cert-sign.kakao.com/sign/doc/v1/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 '{
            "tx_id": "02a05c5bfe-d89a-448b-a538-d80dc5b038fa",
            "return_url": "https://www.sample.com/return_url",
            "expires_in": 1200,
            "identify_items": ["CI", "NAME", "BIRTHDAY", "PHONE_NUMBER", "GENDER"],
            "document_type": "HASH",
            "delegate_info": {
                "request_type": "전자계약",
                "receiver_name": "ajNZRTQ1ait0ZytD" // 암호화 필수
            },
            "documents": [
                {
                    "document_tx_id": "0297e72d72-7e09-4d94-b3f0-1d2eff325ab7",
                    "document_title": "카카오뱅크 거래내역",
                    "document": "{\"txId\": \"0297e72d72-7e09-4d94-b3f0-1d2eff325ab7\",\"data\": \"715cfad410498ece9eea5f9f6d963904cf62341d74379c3dcd76e01e37e6a621\"}"
                },
                ...
            ]
        }'

요청: document_type이 PLAIN_HASH인 단건서명(K3510, K3520)

curl -i -X POST "https://cert-sign.kakao.com/sign/doc/v1/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 '{
            "tx_id": "02a05c5bfe-d89a-448b-a538-d80dc5b038fa",
            "return_url": "https://www.sample.com/return_url",
            "expires_in": 1200,
            "identify_items": ["CI", "NAME", "BIRTHDAY", "PHONE_NUMBER", "GENDER"],
            "document_type": "PLAIN_HASH",
            "delegate_info": {
                "receiver_name": "ajNZRTQ1ait0ZytD" // 암호화 필수
            },
            "document_title": "카카오뱅크 거래내역",
            "document": "715cfad410498ece9eea5f9f6d963904cf62341d74379c3dcd76e01e37e6a621"
        }'

요청: document_type이 PLAIN_HASH인 다건서명(K3511, K3521)

curl -i -X POST "https://cert-sign.kakao.com/sign/doc/v1/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 '{
            "tx_id": "02a05c5bfe-d89a-448b-a538-d80dc5b038fa",
            "return_url": "https://www.sample.com/return_url",
            "expires_in": 1200,
            "identify_items": ["CI", "NAME", "BIRTHDAY", "PHONE_NUMBER", "GENDER"],
            "document_type": "PLAIN_HASH",
            "delegate_info": {
                "request_type": "전자계약",
                "receiver_name": "ajNZRTQ1ait0ZytD" // 암호화 필수
            },
            "documents": [
                {
                    "document_tx_id": "0297e72d72-7e09-4d94-b3f0-1d2eff325ab7",
                    "document_title": "카카오뱅크 거래내역",
                    "document": "715cfad410498ece9eea5f9f6d963904cf62341d74379c3dcd76e01e37e6a621"
                },
                ...
            ]
        }'

응답: 채널 메시지 방식(K3510, K3511)

{
   "tx_id": "02a05c5bfe-d89a-448b-a538-d80dc5b038fa",
   "result": "Y"
}

응답: 앱투앱 방식(K3520, K3521)

{
   "tx_id": "02a05c5bfe-d89a-448b-a538-d80dc5b038fa",
   "result": "Y",
   "scheme": "kakaotalk://…"
}

전자서명 상태 확인하기

기본 정보

전자서명 상태 확인하기 API는 카카오톡 전자서명 K3500 상품으로 요청된 전자서명의 진행 상태를 확인합니다. 사용자는 카카오톡을 통해 인증을 수행하므로, 이용기관은 전자서명 상태 확인하기 API를 통해서만 인증 진행 상태를 확인할 수 있습니다.

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

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

• 요청
  • 사용자에게 전자서명 요청이 전달된 상태
  • 사용자가 전자서명 요청을 정상적으로 확인했다면 viewed_at 필드 값으로 확인 가능
  • 전자서명 상태가 완료 또는 만료로 확인될 때까지 주기적으로 전자서명 확인하기 API 재요청
• 완료
  • 사용자가 전자서명을 완료한 상태(모든 요청이 성공한 경우에 한함, 1건이라도 실패 또는 중단된 경우 인증 실패 처리)
  • 전자서명 검증하기 API를 사용해 결과 값 요청
• 만료
  • 전자서명 요청이 만료된 상태
  • 인증 실패 처리, 또는 전자서명 요청하기 API를 사용해 다시 사용자에게 전자서명 요청

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

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

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

요청

헤더

쿼리 파라미터

응답

본문

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

예제

요청

curl -i -X GET "https://cert-sign.kakao.com/sign/doc/v1/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": "d3a83f53-239d-4d7a-968d-25ec0969047e",
    "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는 카카오톡 전자서명 K3500에 대한 검증을 지원합니다.

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

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

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

전자서명 검증하기 응답 구성은 다음 표를 참고합니다.

* ci: 계약 시 협의한 경우에만 제공

** vid: CI를 제공받고 있거나 VID만 제공하는 상품 이용 시 제공, 자세한 안내는 VID 참고

요청

헤더

쿼리 파라미터

응답

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

본문

signed_document: 전자서명 데이터 전문

예제

요청

curl -i -X GET "https://cert-sign.kakao.com/sign/doc/v1/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"

응답: CI 제공에 협의하지 않은 단건서명(K3510, K3520)

{
    "status": "COMPLETED",
    "result": "Y",
    "signed_document": "${CMSSignedData}"    // 상단 설명 및 표 참고
}

응답: CI 제공에 협의한 단건서명(K3510, K3520)

{
    "status": "COMPLETED",
    "result": "Y",
    "ci": "${CI}",    // 상단 설명 및 표 참고
    "vid": "${VID}",    // 상단 설명 및 표 참고
    "signed_document": "${CMSSignedData}"    // 상단 설명 및 표 참고
}

응답: CI 제공에 협의하지 않은 다건서명(K3511, K3521)

{
    "status": "COMPLETED",
    "result": "Y",
    "signed_documents": [
        {
            "document_tx_id": "0297e72d72-7e09-4d94-b3f0-1d2eff325ab7",    // 상단 설명 및 표 참고
            "signed_document": "${CMSSignedData}"    // 상단 설명 및 표 참고
        }
    ]
}

응답: CI 제공에 협의한 다건서명(K3511, K3521)

{
    "status": "COMPLETED",
    "result": "Y",
    "ci": "${CI}",    // 상단 설명 및 표 참고
    "vid": "${VID}",    // 상단 설명 및 표 참고
    "signed_documents": [
        {
            "document_tx_id": "0297e72d72-7e09-4d94-b3f0-1d2eff325ab7",    // 상단 설명 및 표 참고
            "signed_document": "${CMSSignedData}"    // 상단 설명 및 표 참고
        }
    ]
}

언어별 예제

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

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/doc/v1/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
    }
}

class VerifySample {
 
    private final HttpClient kakaoClient = HttpClient.newBuilder().build();
    private final SecretKeySpec secretKeySpec = new SecretKeySpec(Base64.getDecoder().decode("PARTNER_SECRET_KEY"), "AES");
    private final IvParameterSpec ivSpec = new IvParameterSpec(Base64.getDecoder().decode("PARTNER_IV"));
    private final String settleId = "PARTNER_SETTLE_ID";
 
    private String decrypt(byte[] content) throws NoSuchPaddingException, NoSuchAlgorithmException, IllegalBlockSizeException, BadPaddingException, InvalidAlgorithmParameterException, InvalidKeyException {
        String transformation = "AES/CTR/NoPadding";
        Cipher cipher = Cipher.getInstance(transformation);
        cipher.init(Cipher.DECRYPT_MODE, secretKeySpec, ivSpec);
        return new String(cipher.doFinal(content));
    }
 
    private HttpRequest createHttpRequest(URI uri)  {
        return HttpRequest.newBuilder()
                .uri(uri)
                .setHeader(AUTHORIZATION, DEALER_REST_API_KEY)
                .setHeader(TARGET_AUTHORIZATION, PARTNER_REST_API_KEY)
                .GET()
                .build();
    }
 
    private VerifyResponse callVerify(String txId) throws IOException, InterruptedException {
        URI uri = URI.create(createURI(txId));
        // 전자서명 검증하기 API
        HttpResponse<String> response = kakaoClient.send(createHttpRequest(uri), HttpResponse.BodyHandlers.ofString());
        return Mapper.getInstance().readValue(response.body(), VerifyResponse.class);
    }
 
    private String createURI(String txId) {
        StringBuilder sb = new StringBuilder();
        sb.append("https://cert-sign.kakao.com/sign/doc/v1/verify?settle_id=")
                .append(settleId)
                .append("&tx_id=")
                .append(txId);
        return sb.toString();
    }
 
    /**
     * 이용기관에서 CI를 보유한 경우
     * 전자서명 검증하기 API를 호출하여 보유한 CI와 비교
     * !!중요!! 전자서명 검증하기 API 호출 및 CI 비교는 반드시 서버에서 수행
     */
    // 전자서명 검증하기 API 호출
    boolean compareCI(String txId) throws IOException, InterruptedException, InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException {
        // 응답에 포함된 CI를 복호화
        String encryptedCi = callVerify(txId).getCi();
        // 이용기관에서 보유한 CI와 비교
        String decryptedCI = decrypt(Base64.getDecoder().decode(encryptedCi));
        return exist(decryptedCI);
    }
 
    /**
     * 실명인증된 CI가 있는 경우
     * 전자서명 검증하기 API의 결과와 실명인증된 CI를 비교
     * !!중요!! 전자서명 검증하기 API 호출 및 CI 비교는 반드시 서버에서 수행
     */
    // 전자서명 검증하기 API 호출
    boolean compareCI(String txId, String ci) throws IOException, InterruptedException, InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException {
        // 응답에 포함된 CI를 복호화
        String encryptedCi = callVerify(txId).getCi();
        // 실명인증된 CI와 비교
        String decryptedCI = decrypt(Base64.getDecoder().decode(encryptedCi));
        return ci.equals(decryptedCI);
    }
}

class VerifySample {
private:
    //카카오의 전자서명 검증하기 API를 호출.
    json callVerify(const string& txId) {
        string uri = createURI(txId);
        auto response = kakaoClient.Get(uri.c_str());
        return json::parse(response->body);
    }
 
    string createURI(const string& txId) {
        return "https://cert-sign.kakao.com/sign/doc/v1/verify?settle_id=" + settleId + "&tx_id=" + txId;
    }
 
public:
    /**
     * 이용기관에서 CI를 보유한 경우
     * 전자서명 검증하기 API를 호출하여 보유한 CI와 비교
     * !!중요!! 전자서명 검증하기 API 호출 및 CI 비교는 반드시 서버에서 수행
     */
    // 전자서명 검증하기 API 호출
    bool compareCI(const string& txId) {
        // 응답에 포함된 CI를 복호화
        string encryptedCi = callVerify(txId)["ci"];
        // 이용기관에서 보유한 CI와 비교
        string decryptedCI = decrypt(base64_decode(encryptedCi));
        return exist(decryptedCI);
    }
 
    /**
     * 실명인증된 CI가 있는 경우
     * 전자서명 검증하기 API의 결과와 실명인증된 CI를 비교
     * !!중요!! 전자서명 검증하기 API 호출 및 CI 비교는 반드시 서버에서 수행
     */
    // 전자서명 검증하기 API 호출
    bool compareCI(const string& txId, const string& ci) {
        // 응답에 포함된 CI를 복호화
        string encryptedCi = callVerify(txId)["ci"];
        // 실명인증된 CI와 비교
        string decryptedCI = decrypt(base64_decode(encryptedCi));
        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}",
    "ci": "${CI}",
    "vid": "${VID}"
}

더 보기

• 이해하기
• 문제 해결
• 디자인 가이드