이 문서는 톡디지털카드의 디지털카드 제출 기능에 대한 소개와 API 문서를 제공합니다.

파트너는 디지털카드 제출 연동을 통해, 카카오톡 사용자가 가지고 있는 다양한 디지털카드의 정보를 활용할 수 있습니다. 파트너 서비스의 사용자에게 디지털카드 인증을 거쳐, 서비스 이용 및 혜택을 제공할 수 있도록 디지털카드 정보 활용 및 제공에 대한 동의를 포함한 카카오톡 사용자의 디지털카드 제출 시나리오를 아래와 같이 제공하고 있습니다.

디지털카드 제출 시퀀스 다이어그램

디지털카드 제출 기능은 아래 두 가지 방식으로 구현할 수 있습니다.

• 앱 전환 방식: 사용자가 카카오톡 앱을 직접 실행시켜 디지털카드 제출
• 채널 메시지 방식: 톡디지털카드 공식 카카오톡 채널이 발송한 제출 요청 메시지에서 디지털카드 제출

앱 실행 후 디지털카드 제출

채널 메시지로 디지털카드 제출

아래 이미지는 이해를 돕기 위한 사용자의 디지털카드 제출 과정입니다. 제출 방식에 따라 디지털카드 제출 과정에 차이가 있습니다.

❶ 디지털카드 제출 요청(예: /present-proof/{id} 호출) 페이지와 ❷ 카카오톡 앱 실행은 제출처에서 직접 구현해야 합니다.
여기서 {id}는 제출요청 접수 번호입니다. 앱 실행 스킴 등 자세한 연동 방식은 제휴 계약 후 제출처에게 별도 전달됩니다.

앱 전환 방식 제출 과정

톡디지털카드 공식 카카오톡 채널에서 발급 요청 메시지가 발송됩니다. 제출 요청 메시지는 디지털카드 채널로 사전 정의한 템플릿의 톡메시지가 발송됩니다.

채널 메시지 방식 제출 과정

제출 대상자의 계정 정확성 검증 및 톡학생증 보유 여부 확인을 위해, 제출처 서버에서 제출 요청 API를 호출 할 때 제출 대상자의 전화번호, 이름, 생년월일 정보를 함께 전달해야 합니다.

제출처(파트너)는 제출 대상자(사용자)의 개인정보를 카카오로 전달하게 되므로, 반드시 내부적으로 관련 법령에 따른 개인정보 처리 및 사전 동의 절차를 검토하고 준비해야 합니다.

카카오 디지털카드 서비스는 제출처로부터 전달받은 사용자 식별 정보(전화번호, 이름, 생년월일)를 기반으로 아래의 3가지 항목을 순차적으로 검증하여 제출 절차를 처리합니다.

전달받은 전화번호, 이름, 생년월일과 일치하는 카카오계정이 있는지를 1차로 확인합니다.

일치하는 카카오계정이 없는 경우, 제출 요청시 서버에서 에러 응답을 반환합니다.

일치하는 카카오계정이 있는 경우, 이 정보가 제출을 위해 실행된 카카오톡에 연결된 카카오계정 정보와 일치하는지 2차로 확인합니다. 일치하지 않을 경우, 제출 불가 사유를 안내합니다.

카카오계정 확인 화면

해당 카카오계정이 제출에 필요한 디지털카드를 보유하고 있는지 확인합니다.

디지털카드를 보유하지 않은 경우, 보유카드를 확인하고 발급 받을 수 있도록 안내합니다.

디지털카드 보유 여부 확인 화면

디지털카드 제출 행위에 대한 본인 확인을 위해 카카오 인증서 서명을 진행합니다. 만약 사용자가 카카오 인증서를 보유하고 있지 않다면, 인증서를 먼저 발급받은 뒤 서명할 수 있도록 안내합니다.

카카오 인증서 서명 검증 화면

디지털카드 정보를 제출처에 제공하려면 제출 과정에서 사용자의 동의를 받아야 합니다. 이 동의는 개인정보 제3자 제공에 대한 동의이며, 1회성 제공 동의 방식입니다.

전달 받은 디지털카드 정보의 관리주체는 제출처가 되며, 제공 목적에 맞게 활용해야 합니다. 제공 목적 이외의 이용이 필요한 경우, 제출처에서 직접 필요한 동의를 추가적으로 받아야 합니다.

또한, 제출 동의화면에서 제출처의 채널을 선택적으로 추가할 수 있도록 동의항목을 설정할 수도 있습니다. 이때 제출처의 채널은 제출처의 서비스 앱에 연결된 비즈니스 채널이어야 합니다.

디지털카드 제출 동의 화면

아래는 파트너가 활용 가능한 여러 디지털카드에 대해 소개합니다.

증명서 발급 대행 기관을 통해 카카오톡 지갑에서 발급하는 디지털카드 중 하나로 사용자의 대학 학적 정보를 증명합니다. 톡학생증은 대학명/사용자이름/전공(과) 정보가 포함되며 대학생, 대학원생, 졸업생 3가지 카드 중 최종 학력 기준으로 발급됩니다.

톡학생증 예시 화면

정부24 전자증명서를 통해 카카오톡 지갑에서 발급하는 디지털카드 중 하나로 사용자의 재직 및 경력을 증명합니다. 동일한 카카오 인증서로 다른 카카오계정에서 톡사원증을 재발급할 경우, 기존에 발급된 모든 카드는 자동으로 삭제됩니다.

톡사원증 예시 화면

만 14세 이상부터 발급이 가능한 카드로, 카카오계정 본인인증 정보로 본인의 연령을 인증하고 청소년 대상 혜택을 누릴 수 있는 디지털카드입니다.

틴카드 예시 화면

카카오 전자증명서에서 발급한 주민등록등본을 통해 사용자의 거주지 주소 정보 확인 후 발급되는 디지털카드로 주소 관련 정보와 함께 전입일/전입일로부터 거주한 기간 등의 정보가 포함됩니다.

동네카드 예시 화면

카카오 전자증명서에서 발급한 국가기술자격증 확인 증명서(발급처: 한국산업인력공단, 대한상공회, 한국방송통신전파진흥원)를 통해 사용자의 자격정보 확인 후 발급되는 카드로 자격번호, 합격일자 등 자격 관련 상세 정보가 포함됩니다.

자격카드 예시 화면

국가동물보호정보시스템의 동물등록정보 또는 직접 입력한 정보로 발급된 반려동물의 디지털 신분증입니다. 반려동물 사진 및 이름, 생년월일, 동물등록정보 등의 상세 정보가 포함됩니다.

반려동물카드 예시 화면

카카오 전자증명서에서 발급한 주민등록등본을 통해 발급되는 디지털카드로, 자녀가 있는 세대주이거나 세대주의 배우자인 경우 발급할 수 있습니다. 아이 이름, 생년월일, 성별 정보가 포함됩니다.

아이카드 예시 화면

1. 카카오디벨로퍼스 앱을 생성 해 서비스 정보를 등록합니다. 기존 앱의 설정과 사용자 정보를 그대로 사용할 수도 있습니다.
2. 앱에 사업자 정보를 등록해 비즈 앱으로 전환합니다.
   • 중요: 비즈 앱의 사업자 정보는 디지털카드 발급처의 사업자 정보와 동일해야 합니다.
3. 디지털카드 동의 화면이나 제출 요청 메시지를 보낼 비즈니스 채널을 생성합니다.
4. 앞서 생성한 비즈 앱과 비즈니스 채널을 연결합니다.
5. 사용할 어드민 키에 호출 허용 IP 주소를 등록합니다.
   • 중요: 톡디지털카드 API는 서버에서 앱 어드민 키(Admin key)를 사용해 호출하므로, 보안을 위해 반드시 허용 IP를 등록해야 합니다.
6. 파트너스 아지트로 파트너 등록 정보와 디지털카드 제출 항목 정보를 제출합니다.
7. 파트너 체크리스트를 참고해 제출처에서 검토하고 결정해야 하는 항목을 준비합니다.
8. 제출 과정을 참고해 필요한 기능을 연동합니다. API 연동 중 문제가 발생한 경우, FAQ를 참고하거나 제휴 담당자에게 문의합니다.
   • 디지털카드 제출 요청 API
   • 디지털카드 제출 동선 상태 조회 API
9. 기능 구현 후, 톡학생증 테스트카드를 발급 받아 연동 과정을 테스트합니다.

카카오에게 전달해야 하는 파트너(제출처)의 정보입니다.

• 파트너명: 디지털카드를 제공 받고자하는 파트너의 서비스명 전달 필요, 디지털카드 제출 과정에서 해당 서비스명이 노출됨
• 앱 ID: 제출 API의 사용 권한을 부여할 카카오디벨로퍼스 앱의 ID 전달
• 제출 웹훅 URL: 제출 결과 정보를 받을 제출 파트너의 서버 URL
  • 중요: 제출 파트너 시스템에 방화벽이 설정되어 있다면, 제출 웹훅 URL이 외부에서도 접근 가능한지 미리 확인해야 합니다. 카카오가 서버를 호출할 때 사용하는 IP 정보를 미리 등록해야 하는 경우, 카카오 측에서 해당 IP 정보를 받아 사전에 등록해야 합니다.
• 허용 IP 주소: 앱 어드민 키를 사용해 호출해야 하기 때문에, 보안 유지를 위한 허용 IP 주소 등록 필수, API를 호출하는 서버의 IP를 파트너 등록 정보 전달 시 함께 전달해야 함
  • 중요: 등록하지 않은 IP로 요청하는 API 호출은 모두 실패합니다.
• 파트너 인증 키: 제출 웹훅을 호출하기 위해 인증 키가 필요할 경우 전달(선택)

카카오에게 전달해야 하는 제출 항목 정보입니다.

• [선택] 채널 추가 동의항목 활용 여부
  • 디지털카드 제출 플로우에서 사용자에게 이용약관 동의를 받을 때, 파트너의 카카오톡 채널을 추가(선택 동의)할 수 있도록 설정 가능
• 위의 동의항목 활용 시, 카카오톡 채널 프로필 ID(참고: 카카오톡 채널 프로필 ID 확인 방법)
  • 카카오톡 채널은 카카오디벨로퍼스 앱에 연결된 비즈니스 채널이어야 함
• 제출 대상 카드 범위: 제출가능한 디지털카드 목록을 참고하여, 제출받고자 하는 디지털카드의 범위 전달
• 제출 완료 시, 제공받고자 하는 정보: 카카오와 논의 후 확정

디지털카드 제출 기능 연동 시, 파트너에서는 아래 사항을 준비해야 합니다.

제출 연동 과정이 정상적으로 동작하는지 확인하기 위해, 톡학생증 테스트카드를 발급해 테스트하는 방법을 설명합니다. 톡학생증 이외의 카드는 별도의 테스트카드 발급을 지원하지 않습니다.

1. 파트너스 아지트에서 [테스트카드 발급요청] 글양식을 활용해 신청합니다.
   • 개인정보 제공 동의가 필요하여 테스트 사용자별로 각각 신청 필요
2. 신청한 휴대전화번호로 테스트카드 발급이 가능한 [디지털카드 발급안내] 채널 메시지가 발송됩니다.
3. 채널 메시지의 [발급하기] 버튼을 눌러, 발급을 진행합니다. 발급이 완료되면 "발급이 완료되었습니다." 화면이 나타납니다.
   • 주의: 발급된 테스트카드는 절대 외부에 공유, 공개 및 활용 불가
4. [카카오톡] > [더보기] > [디지털카드]에서 발급된 카드를 확인합니다.
5. 제출 요청 API를 호출해 전달 받은 transactionId로 앱스킴을 호출하면 카카오톡이 실행되며 제출 웹뷰가 열립니다.
6. 발급된 테스트카드로 제출 연동 플로우를 테스트합니다.
   • 테스트 시, 인증서를 발급하여 인증 필요
7. 테스트 환경을 파트너스 아지트로 공유합니다. 카카오에서 제출 연동 과정에 문제가 없는지 확인하고 있습니다. 가능한 선에서 테스트 환경 공유 부탁드립니다.

디지털카드 제출 연동 테스트 흐름

테스트 시, 아래 사항을 유의합니다. 테스트 완료 후, 테스트카드는 카카오에서 삭제합니다.

• 테스트 카드는 테스트용 presentationDefinitionId에서만 작동이 가능합니다.
• 운영용 presentationDefinitionId에서는 테스트카드로 제출할 수 없습니다.
• 테스트가 완료되면, 반드시 운영용 presentationDefinitionId로 변경 및 반영해야 합니다.

디지털카드 제출을 요청합니다.

어드민 앱 키를 헤더에 담아 POST로 요청합니다. 제출 대상 사용자의 정보와 제출 데이터 명세 ID를 전달합니다.

요청이 성공 시 제출데이터 명세 고유 번호가 반환됩니다. 요청 실패 시 에러 코드에서 에러 코드로 원인을 확인합니다.

curl -X POST "https://digitalcard-partner.kakao.com/present-proof/request" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: KakaoAK {SERVICE_APP_ADMIN_KEY}" \
  -d '{
    "account": {
      "phoneNumber": "821012341234",
      "name": "홍길동",
      "birthday": "20020202"
    },
    "presentationDefinitionId": "1edb31bb-ecb5-66ec-b3ae-ff92cca340b6",
    "sendTms": false
  }'

// HTTP/1.1 200 OK
{
  "transactionId": "1edc4982-4069-6c38-b9ad-91cd3271f081"
}

현재 사용자의 제출 동선 상태를 확인합니다.

어드민 앱 키를 헤더에 담아 GET으로 요청합니다. {id} 경로 변수에 제출 요청 접수 번호를 전달합니다.

요청이 성공 시 제출 상태와 제출된 사용자 정보 등 상세 정보가 반환됩니다. 요청 실패 시 에러 코드에서 에러 코드로 원인을 확인합니다.

각 카드의 credentialSubject는 제출 Definition에 따라 그 구조 및 포함 필드가 다를 수 있습니다. 아래는 톡학생증과 톡사원증의 데이터 구조 예시입니다.

curl -L -X GET 'https://digitalcard-partner.kakao.com/present-proof/1edb95a8-09cf-6312-b32c-89128665d7c4' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: KakaoAK {SERVICE_APP_ADMIN_KEY}'

// HTTP/1.1 200 OK
{
  "id": "1edb95a8-09cf-6312-b32c-89128665d7c4",
  "presentationDefinitionId": "1edb31bb-ecb5-66ec-b3ae-ff92cca340b6",
  "state": "REQUESTED",
  "reason": null,
  "updatedAt": "2022-11-22T20:27:36.482866",
  "createdAt": "2022-11-22T20:27:36.482866",
  "verifiablePresentation": {
    "type": ["VerifiablePresentation"],
    "@context": ["https://www.w3.org/2018/credentials/v1"],
    "verifiableCredential": [
      {
        "type": ["EmployeeId", "VerifiableCredential"],
        "@context": ["https://schema.org", "https://www.w3.org/2018/credentials/v1"],
        "credentialSubject": {
          "organization": {
            "name": "회사명",
            "id": "사업장번호"
          }
        }
      }
    ]
  }
}

디지털카드 발급 및 삭제 과정에 필요한 정보를 요청하거나 전달하기 위해, 톡디지털카드 서비스에서 발급처에 호출합니다. 웹훅(Webhook) URL은 제휴 계약 시 파트너 등록 과정에서 설정합니다. 필요 시, 파트너는 인증을 위한 파트너 인증 키(PARTNER_API_KEY)를 톡디지털카드 서비스에 전달해 웹훅 호출 시 사용하도록 요청할 수 있습니다.

사용자가 디지털카드를 외부 서비스나 제출처에 제출하는 경우, 해당 제출 결과를 발급처에 전달하기 위해 호출되는 웹훅입니다.

제출처는 제출 결과에 따라 적절한 후속 처리를 할 수 있습니다.

curl -L -X POST 'example.webhook.url' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {PARTNER_API_KEY}' \
  -d '{
    "state": "PROOF_PRESENTED",
    "presentationTransactionId": "1edb31bb-ecb5-66ec-b3ae-ff92cca340b6",
    "verifiablePresentation": {
      "@context": [
        "https://www.w3.org/2018/credentials/v1"
      ],
      "type": [
        "VerifiablePresentation"
      ],
      "verifiableCredential": [{
        "type": [
          "EmployeeId",
          "VerifiableCredential"
        ],
        "@context": [
          "https://schema.org",
          "https://www.w3.org/2018/credentials/v1"
        ],
        "credentialSubject": {
          "organization": {
            "name": "회사명",
            "id": "사업장번호"
          }
        }
      }]
    }
  }'

curl -L -X POST 'example.webhook.url' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {PARTNER_API_KEY}' \
  -d '{
    "state": "PROOF_ABANDONED",
    "presentationTransactionId": "1edb31bb-ecb5-66ec-b3ae-ff92cca340b6",
    "reason": "CARD_NOT_EXIST"
  }'

• 이해하기
• 디지털카드 발급
• 에러 코드
• FAQ
• 디자인 가이드