디지털카드 발급

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

디지털카드 발급 소개

카카오가 발급하는 톡학생증, 톡사원증 외에도 제휴 서비스–발급처가 원하는 다양한 카드를 직접 기획/연동하여, 사용자에게 발급 서비스를 제공하고, 일련의 발급과정을 거쳐 사용자의 카카오톡 지갑에 담을 수 있습니다.

톡디지털카드와 관련된 주요 정책은 다음과 같으며 세부 정책 수립, 연동 운영 방식에 있어서 카카오와의 계약 및 협의가 필요합니다.

디지털카드는 카카오톡에 가입된 국내 사용자의 카카오계정에 발급됩니다.
카드에는 발급처에서 지정한 카드데이터(속성 정보)를 포함시킬 수 있습니다.
카드의 발급 및 관리, 회수는 발급처에서 관리합니다.

톡디지털카드에 대한 자세한 사항은 이해하기를 참고합니다.

제휴 안내

톡디지털카드는 카카오와 제휴 계약 체결 후 이용할 수 있습니다. 제휴 문의는 카카오 제휴 안내 사이트에서 가능합니다.

발급 방식

디지털카드 발급 방식은 두 가지가 있습니다.

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

앱 전환 방식

아래 이미지는 이해를 돕기 위한 사용자의 디지털카드 발급 과정입니다. ❶디지털카드 발급 요청 페이지와 ❷ 카카오톡 앱 실행은 발급처에서 직접 구현해야 합니다.

앱 전환 발급 방식

채널 메시지 방식

톡디지털카드 공식 카카오톡 채널에서 발급 요청 메시지가 발송됩니다.

채널 메시지 발급 방식

발급 과정

채널 메시지 발급 과정

디지털카드 만들기

데이터 생성 API를 요청해 새로운 디지털카드 데이터 명세를 생성합니다.
- 생성한 발급데이터 명세 고유 번호(credentialDefinitionId)가 응답으로 반환됩니다.
- 데이터 정보 조회 API로 생성한 데이터 명세를 확인하고, 데이터 수정 API로 수정할 수 있습니다.
디자인 명세 생성 API를 요청해 데이터 명세에 적용할 디자인 명세를 생성합니다.
- 적용된 디자인 명세 고유 번호(designDefinitionId)가 응답으로 반환됩니다.
- 디자인 명세 조회 API로 적용한 디자인 명세를 확인하고, 디자인 명세 수정 API로 수정할 수 있습니다.

디지털카드 발급하기

발급 제안 API를 요청하면 톡디지털카드 서버에서 사용자에게 앱투앱(App to app) 또는 채널 메시지 방식으로 해당 디지털카드 발급을 제안합니다.
- 발급 방식을 참고합니다.
사용자는 발급 미리보기 페이지를 확인하고 파트너가 설정한 동의항목과 본인 확인 절차를 거쳐 디지털카드를 발급받습니다.
발급 대상 검증이 필요한 경우 톡디지털카드 서버는 사용자 정보 요청 웹훅으로 발급처에 사용자 정보를 확인합니다.
디지털카드 발급이 가능한 경우, 톡디지털카드 서버는 발급 요청 웹훅으로 발급처에 이를 전달합니다.
발급처는 발급 요청 웹훅을 받은 후 발급 처리 API를 요청해 디지털카드를 발급할 수 있습니다.
- 발급된 디지털카드의 고유 번호(cardId)가 응답으로 반환됩니다.

디지털카드 회수하기

발급 회수 API를 요청하면 톡디지털카드 서버에서 사용자에게 발급된 디지털카드를 회수합니다.

발급 대상 검증

발급 대상의 카카오계정 정확성을 검증하기 위해 카카오계정 본인인증 또는 카카오톡 인증 서비스를 활용한 전자서명을 발급 과정에 추가할 수 있습니다. 발급처가 보유한 본인 확인 정보와 카카오계정의 본인 정보를 비교해 디지털카드 발급 대상의 동일성을 확인합니다.

아래 이미지는 이해를 돕기 위한 사용자의 본인인증이 포함된 발급 과정입니다.

카카오계정 본인인증 과정 추가 발급 대상 검증

* 본인인증되지 않은 카카오계정이거나 계정 정보가 서비스와 다르면 발급되지 않음

카카오톡 인증 서비스 전자서명 과정 추가 발급 대상 검증

* 카카오 인증서가 없는 계정은 인증서 발급 과정을 먼저 수행

연동 방법

카카오디벨로퍼스 앱을 생성 해 서비스 정보를 등록합니다. 기존 앱의 설정과 사용자 정보를 그대로 사용할 수도 있습니다.
앱에 사업자 정보를 등록해 비즈 앱으로 전환합니다.
- 중요: 비즈 앱의 사업자 정보는 디지털카드 발급처의 사업자 정보와 동일해야 합니다.
디지털카드 동의 화면이나 제출 요청 메시지를 보낼 비즈니스 채널을 생성합니다.
앞서 생성한 비즈 앱과 비즈니스 채널을 연결합니다.
API를 호출할 서버의 IP를 허용 IP 주소로 등록합니다.
- 중요: 톡디지털카드 API는 서버에서 앱 어드민 키(Admin key)를 사용해 호출하므로, 보안을 위해 반드시 허용 IP를 등록해야 합니다. 만약 다른 카카오 API도 함께 사용하는 경우, 해당 API를 호출하는 서버의 IP도 모두 등록해야 합니다.
카카오 로그인 기능을 사용 설정합니다.
발급 과정을 참고해 필요한 기능을 연동합니다.

디지털카드 데이터 API

생성

기본 정보

메서드	URL	인증 방식
`POST`	`https://digitalcard-partner.kakao.com/issue-credential/definitions`	서비스 앱 어드민 키

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

새로운 디지털카드의 데이터 명세를 만듭니다.

발급 이력이 없는 데이터 명세은 수정하기로 데이터를 수정할 수 있습니다. 디지털카드 발급으로 사용자에게 발급할 수 있습니다.

어드민 앱 키를 헤더에 담아 POST로 요청합니다. 생성할 디지털카드의 데이터를 파라미터로 포함해야 합니다.

요청 성공 시 응답 헤더에 생성된 디지털카드 고유 번호가 입력된 리다이렉트(Redirect) URI가 헤더에 포함됩니다. 응답 본문은 생성한 발급데이터 명세 고유 번호(credentialDefinitionId)를 포함하는 JSON 객체입니다. 요청 실패 시 에러 코드에서 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

본문

이름	타입	설명	필수
name	`String`	디지털카드 이름	O
cardName	`String`	카드명 규칙 카드마다 다른 카드명을 적용하고 싶을 때 사용 카드 데이터의 어떤 값을 카드명에 포함할지 JSON 경로로 지정 가능 `{{$.credentialSubject.${FIELD_NAME}}}` 형식, 예제 참고 참고: `cardName` 지정 없이 카드 발급 시, 카드명은 `name` 값으로 지정	X
properties	`Object`	디지털카드의 데이터별 규격 객체, 예제 참고	O
needServiceTerm	`Boolean`	디지털카드 발급 시 파트너 약관 동의항목 필요 여부, 파트너 약관 참고	O
termsUrl	`String`	파트너 약관 URL(기본값: `null`) 참고: `needServiceTerm`이 `true`인 경우 설정 필요	X
authLevel	`String`	디지털카드 발급 대상 검증 방법, 발급 대상 검증 참고, 아래 중 하나 `NONE`: 검증 안함 `ACCOUNT_AUTH`: 카카오 계정 본인인증 `SIGN`: 카카오 인증서 서명	O
channelPublicId	`String`	발급처 카카오톡 채널 ID, 채널 메시지 참고	X
needChannelPlus	`Boolean`	디지털카드 발급 시 선택동의로 채널 추가 노출 여부 (기본값 `true`), 카카오톡 채널 친구 추가 참고	X

응답

헤더

이름	설명	필수
Location	`Location: /issue-credential/definitions/${CREDENTIAL_DEFINITION_ID}` 리다이렉트 URI	O

본문

이름	타입	설명	필수
credentialDefinitionId	`String`	발급데이터 명세 고유 번호	O

예제

요청

curl -L -X POST 'https://digitalcard-partner.kakao.com/issue-credential/definitions' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}' \
  -d '{
        "name": "ifkakao기념카드",
        "properties": {
            "author": {
                "name": "https://schema.org/name"
            },
            "datePublished": "https://schema.org/datePublished"
        },
        "needServiceTerm": false,
        "authLevel": "NONE",
        "channelPublicId": "_CiN",
        "cardName": "{{$.credentialSubject.author.name}} 카드"
    }'

응답

// 201 Created
// Location: /issue-credential/definitions/1ed8024a-cb4d-6341-a94b-2f025d46c87c
{
  "credentialDefinitionId": "1ed8024a-cb4d-6341-a94b-2f025d46c87c"
}

단건 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://digitalcard-partner.kakao.com/issue-credential/definitions/{CREDENTIAL_DEFINITION_ID}`	서비스 앱 어드민 키

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

디지털카드 데이터를 확인합니다.

어드민 앱 키를 헤더에 담아 GET으로 요청합니다. 요청 URL에 경로 변수(Path variable)로 발급데이터 명세 고유 번호(credentialDefinitionId)를 포함해 특정 디지털카드 데이터만 확인할 수 있습니다.

요청 성공 시 응답은 디지털카드 데이터 객체입니다. 요청 실패 시 에러 코드에서 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

경로 변수

이름	타입	설명	필수
CREDENTIAL_DEFINITION_ID	`String`	조회할 발급데이터 명세 고유 번호, 예제 참고	X

응답

본문

이름	타입	설명	필수
credentialDefinitionResponse	`CredentialDefinitionResponse`	디지털카드 데이터 정보	O

CredentialDefinitionResponse

이름	타입	설명	필수
id	`String`	발급데이터 명세 고유 번호	O
name	`String`	디지털카드 이름	O
cardName	`String`	카드명 규칙	X
properties	`Object`	디지털카드의 데이터별 규격 객체, 키와 값의 쌍으로 구성, 예제 참고	O
needServiceTerm	`Boolean`	디지털카드 발급 시 파트너 약관 동의항목 필요 여부, 파트너 약관 참고	O
termsUrl	`String`	파트너 약관 URL(기본값: `null`)	O
authLevel	`String`	디지털카드 발급 대상 검증 방법, 발급 대상 검증 참고, 아래 중 하나 `NONE`: 검증 안함 `ACCOUNT_AUTH`: 카카오 계정 본인인증 `SIGN`: 카카오 인증서 서명	O
channelPublicId	`String`	발급처 카카오톡 채널 ID, 채널 메시지 참고	O
state	`String`	디지털카드 활성화 여부 `true`: 활성 `false`: 비활성	O

예제

요청

curl -L -X GET 'https://digitalcard-partner.kakao.com/issue-credential/definitions/${CREDENTIAL_DEFINITION_ID} \
    -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}'

응답

// HTTP/1.1 200 OK
{
  "name": "브런치 작가 카드",
  "context": ["https://www.w3.org/2018/credentials/examples/v1", "https://schema.org"],
  "type": ["Author Card"],
  "properties": {
    "author": {
      "name": "https://schema.org/name"
    },
    "datePublished": "https://schema.org/datePublished"
  },
  "needServiceTerm": false,
  "termsUrl": null,
  "authLevel": "NONE",
  "channelPublicId": "_CiN",
  "needChannelPlus": true,
  "state": "ACTIVE"
}

전체 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://digitalcard-partner.kakao.com/issue-credential/definitions`	서비스 앱 어드민 키

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

디지털카드 데이터를 확인합니다.

어드민 앱 키를 헤더에 담아 GET으로 요청합니다.

요청 성공 시 응답은 각 디지털카드 데이터를 값으로 갖는 List입니다. 요청 실패 시 에러 코드에서 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

응답

본문

이름	타입	설명	필수
credentialDefinitionResponse	`CredentialDefinitionResponse[]`	디지털카드 데이터 리스트	O

CredentialDefinitionResponse

이름	타입	설명	필수
id	`String`	발급데이터 명세 고유 번호	O
name	`String`	디지털카드 이름	O
cardName	`String`	카드명 규칙	X
properties	`Object`	디지털카드의 데이터별 규격 객체, 키와 값의 쌍으로 구성, 예제 참고	O
needServiceTerm	`Boolean`	디지털카드 발급 시 파트너 약관 동의항목 필요 여부, 파트너 약관 참고	O
termsUrl	`String`	파트너 약관 URL(기본값: `null`)	O
authLevel	`String`	디지털카드 발급 대상 검증 방법, 발급 대상 검증 참고, 아래 중 하나 `NONE`: 검증 안함 `ACCOUNT_AUTH`: 카카오 계정 본인인증 `SIGN`: 카카오 인증서 서명	O
channelPublicId	`String`	발급처 카카오톡 채널 ID, 채널 메시지 참고	O
state	`String`	디지털카드 활성화 여부 `true`: 활성 `false`: 비활성	O

예제

요청

curl -L -X GET 'https://digitalcard-partner.kakao.com/issue-credential/definitions' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}'

응답

// HTTP/1.1 200 OK
[
  {
    "id": "1ed513ba-6dfb-6fac-8055-cba3246a4667",
    "name": "학생인증카드",
    "properties": ["alumniOf"],
    "needServiceTerm": true,
    "authLevel": "SIGN",
    "channelPublicId": "_CiN",
    "termsUrl": "https://www.kakao.com/policy/terms?type=a&lang=ko",
    "state": "ACTIVE"
  },
  {
    "id": "1ed76d7a-3c17-61ac-9e27-0710cdad622b",
    "name": "브런치 작가 카드",
    "context": ["https://www.w3.org/2018/credentials/examples/v1", "https://schema.org"],
    "type": ["Author Card"],
    "properties": {
      "author": {
        "name": "https://schema.org/name"
      },
      "datePublished": "https://schema.org/datePublished"
    },
    "needServiceTerm": false,
    "authLevel": "NONE",
    "channelPublicId": "_CiNNN",
    "termsUrl": null,
    "state": "ACTIVE",
    "cardName": "{{$.credentialSubject.author.name}} 카드"
  }
]

수정

기본 정보

메서드	URL	인증 방식
`PATCH`	`https://digitalcard-partner.kakao.com/issue-credential/definitions/${CREDENTIAL_DEFINITION_ID}`	서비스 앱 어드민 키

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

특정 디지털카드 데이터를 수정합니다.

발급 이력이 없는 데이터 명세(credentialDefinition)만 수정 가능합니다.

어드민 앱 키를 헤더에 담아 PATCH로 요청합니다. 요청 URL에 경로 변수(Path variable)로 발급데이터 명세 고유 번호(credentialDefinitionId)를 포함해야 합니다.

요청 성공 시 응답 헤더에 수정된 디지털카드 고유 번호가 입력된 리다이렉트(Redirect) URI가 포함됩니다. 응답 본문은 수정된 디지털카드 데이터가 포함된 JSON 객체입니다. 요청 실패 시 에러 코드에서 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O
Content-Type	`Content-Type: application/merge-patch+json` 요청 데이터 타입	O

경로 변수

이름	타입	설명	필수
CREDENTIAL_DEFINITION_ID	`String`	디지털카드 고유 번호	O

본문

이름	타입	설명	필수
name	`String`	디지털카드 이름	X
cardName	`String`	카드명 규칙 카드마다 다른 카드명을 적용하고 싶을 때 사용 카드 데이터의 어떤 값을 카드명에 포함할지 JSON 경로로 지정 가능 `{{$.credentialSubject.${FIELD_NAME}}}` 형식 참고: `cardName` 지정 없이 카드 발급 시, 카드명은 `name` 값으로 지정	X
needServiceTerm	`Boolean`	디지털카드 발급 시 파트너 약관 동의항목 필요 여부, 파트너 약관 참고	X
termsUrl	`String`	파트너 약관 URL(기본값: `null`) 참고: `needServiceTerm`이 `true`인 경우 설정 필요	X
authLevel	`String`	디지털카드 발급 대상 검증 방법, 발급 대상 검증 참고, 아래 중 하나 `NONE`: 검증 안함 `ACCOUNT_AUTH`: 카카오 계정 본인인증 `SIGN`: 카카오 인증서 서명	X
channelPublicId	`String`	발급처 카카오톡 채널 ID	X
state	`String`	디지털카드 활성화 여부 `true`: 활성 `false`: 비활성	X

응답

헤더

이름	설명	필수
Location	`Location: /issue-credential/definitions/${CREDENTIAL_DEFINITION_ID}` 리다이렉트 URI	O

본문

이름	타입	설명	필수
credentialDefinitionResponse	`CredentialDefinitionResponse`	디지털카드 데이터	O

예제

요청

curl -L -X PATCH 'https://digitalcard-partner.kakao.com/issue-credential/definitions/1ed513ba-6dfb-6fac-8055-cba3246a4667' \
  -H 'Content-Type: application/merge-patch+json' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}' \
  -d '{
        "name": "카카오 학생인증카드"
    }'

응답

// HTTP/1.1 200 OK
// Location: /issue-credential/definitions/1ed513ba-6dfb-6fac-8055-cba3246a4667
{
  "id": "1ed513ba-6dfb-6fac-8055-cba3246a4667",
  "name": "카카오 학생인증카드",
  "context": ["https://www.w3.org/2018/credentials/examples/v1", "https://schema.org"],
  "type": ["Author Card"],
  "properties": {
    "author": {
      "name": "https://schema.org/name"
    },
    "datePublished": "https://schema.org/datePublished"
  },
  "needServiceTerm": false,
  "authLevel": "NONE",
  "channelPublicId": "_CiNNN",
  "termsUrl": null,
  "state": "ACTIVE"
}

디지털카드 디자인 API

디자인 명세 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://digitalcard-partner.kakao.com/designs/definitions/${DESIGN_DEFINITION_ID}`	서비스 앱 어드민 키

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

특정 디지털카드의 디자인 명세 정보를 조회합니다.

어드민 앱 키를 헤더에 담아 GET으로 요청합니다. 조회할 디자인 명세 고유 번호(DESIGN_DEFINITION_ID)를 경로 변수로 포함해야 합니다.

요청 성공 시 응답은 디자인 명세 정보가 포함된 JSON 객체입니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

경로 변수

이름	타입	설명	필수
DESIGN_DEFINITION_ID	`String`	디자인 명세 고유 번호(`designDefinitionId`)	O

응답

본문

이름	타입	설명	필수
-	`DesignDefinitionResponse`	디자인 명세 정보 객체	O

DesignDefinitionResponse

이름	타입	설명	필수
id	`String`	디자인 명세 고유 번호(`designDefinitionId`)	O
name	`String`	디자인 명세 이름	O
credentialDefinitionId	`String`	디자인 명세가 적용된 카드 발급데이터 명세 고유 번호	O
designTemplateCode	`String`	디자인 명세에서 사용할 카드 템플릿 코드, 아래 중 하나 `PROFILE_A`: 프로필A `PROFILE_B`: 프로필B `HEADLINE_A`: 헤드라인A `HEADLINE_B`: 헤드라인B `HEADLINE_C`: 헤드라인C `IMAGE`: 이미지	O
content	`Content`	카드 템플릿 설정	O
designActions	`Action[]`	기능 버튼 설정	X
designHome	`Home`	톡디지털카드 홈 설정	X
designDetails	`Details`	카드 정보 설정	X

Content

이름	타입	설명	필수
textColor	`String`	카드 템플릿의 텍스트 색상, 아래 중 하나 `WHITE`: 흰색 `BLACK`: 검은색(기본값)	X
backgroundImageName	`String`	카드 템플릿의 카드 이미지 파일명(형식: `PNG`)	O
title	`ValueContent`	카드 템플릿의 타이틀 텍스트	X
subTitle	`ValueContent`	카드 템플릿의 서브 타이틀 텍스트	X
infos	`TitleValueContent[]`	카드 템플릿의 카드 정보	X
badge	`ValueContent`	카드 우측 상단 배지 텍스트	X

ValueContent

이름	타입	설명	필수
value	`String`	텍스트에 적용할 문구, JSONata 포맷 지원(참고)	O
jsonataInput	`Object`	`value`가 JSONata 포맷인 경우 표현식에서 사용할 데이터(기본값: `null`)	X

TitleValueContent

이름	타입	설명	필수
title	`String`	정보 이름 텍스트에 적용할 문구	O
value	`String`	정보 값 텍스트에 적용할 문구, JSONata 포맷 지원(참고)	O
jsonataInput	`Object`	`value`가 JSONata 포맷인 경우 표현식에서 사용할 데이터(기본값: `null`)	X

Action

이름	타입	설명
value	`String`	기능 버튼 이름
landingUrl	`String`	기능 버튼 선택 시 이동할 URL

Home

이름	타입	설명	필수
logoName	`String`	톡디지털카드 홈에 표시할 로고 이미지 파일명	O
thumbnailName	`String`	톡디지털카드 홈에 표시할 썸네일 이미지 파일명	O
backgroundImageUrl	`String`	지갑홈 카드의 배경 이미지 URL	X
backgroundColors	`String[]`	지갑홈 카드의 배경 그라데이션 색상 정보 좌측 상단과 우측 하단, 2개의 색상 코드값 필요 (`#000000` 형식)	X
theme	`String`	카드의 색상 테마 `DARK` 또는 `LIGHT` 중 하나	X

Details

이름	타입	설명	필수
backgroundImageName	`String`	카드 정보에 표시할 백그라운드 이미지 파일명	X
info	`DetailsInfo`	세부 정보 내용	X
descriptions	`String[]`	참고 정보 텍스트	X

DetailsInfo

이름	타입	설명	필수
title	`String`	세부 정보 타이틀 텍스트	O
value	`String`	세부 정보 값 텍스트, JSONata 포맷 지원(참고)	O
image	`String`	세부 정보 이미지 파일명	X
link	`String`	`value` 문구 선택 시 이동할 링크 URL	X
jsonataInput	`Object`	`value`가 JSONata 포맷인 경우 표현식에서 사용할 데이터(기본값: `null`)	X

예제

요청

curl -L -X GET 'https://digitalcard-partner.kakao.com/designs/definitions/${DESIGN_DEFINITION_ID}' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}'

응답

{
  "id": "1ef6e602-fbe0-6986-9313-d97e58edc574",
  "name": "동네카드 기본",
  "credentialDefinitionId": "1ef6e5ec-0206-6292-9313-d97e58edc574",
  "designTemplateCode": "PROFILE_B",
  "content": {
    "textColor": "BLACK",
    "backgroundImageName": "static.png",
    "title": {
      "value": "{{$.credentialSubject.region1}} {{$.credentialSubject.region2}}",
      "jsonataInput": null
    },
    "subTitle": {
      "value": "3년째 거주중입니다.",
      "jsonataInput": null
    },
    "info1": {
      "title": "전입일",
      "value": "2020. 12. 31.",
      "jsonataInput": null
    },
    "info2": {
      "title": "이름",
      "value": "{{$.credentialSubject.name}}",
      "jsonataInput": null
    },
    "badge": null
  },
  "designActions": [
    {
      "value": "트렌드랭킹",
      "landingUrl": "https://www.daum.net"
    }
  ],
  "designHome": {
    "logoName": "ico_localcard.png",
    "thumbnailName": "img_logo_localcard.png"
  },
  "designDetails": {
    "backgroundImageName": null,
    "info": [
      {
        "title": "이름",
        "value": "{{$.credentialSubject.name}}"
      },
      {
        "title": "주소",
        "value": "{{$.credentialSubject.roadAddress}}"
      },
      {
        "title": "전입일",
        "value": "2020. 12. 31."
      }
    ],
    "descriptions": ["카카오톡 전자증명서로 발급되었습니다."]
  }
}

전체 디자인 명세 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://digitalcard-partner.kakao.com/designs/definitions`	서비스 앱 어드민 키

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

파트너가 소유한 전체 디지털카드 디자인 명세 정보를 조회합니다.

어드민 앱 키를 헤더에 담아 GET으로 요청합니다. 요청 성공 시 응답은 디자인 명세 정보가 포함된 배열입니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

응답

본문

이름	타입	설명	필수
definitions	`DesignDefinitionResponse[]`	디자인 명세 정보 배열	O

예제

요청

curl -L -X GET 'https://digitalcard-partner.kakao.com/designs/definitions' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}'

응답

{
  "definitions": [
    {
      "id": "1ef6e602-fbe0-6986-9313-d97e58edc574",
      "name": "동네카드 기본",
      "credentialDefinitionId": "1ef6e5ec-0206-6292-9313-d97e58edc574",
      "designTemplateCode": "PROFILE_B",
      "content": {
        "textColor": "BLACK",
        "backgroundImageName": "static.png",
        "title": {
          "value": "{{$.credentialSubject.region1}} {{$.credentialSubject.region2}}",
          "jsonataInput": null
        },
        "subTitle": {
          "value": "3년째 거주중입니다.",
          "jsonataInput": null
        },
        "info1": {
          "title": "전입일",
          "value": "2020. 12. 31.",
          "jsonataInput": null
        },
        "info2": {
          "title": "이름",
          "value": "{{$.credentialSubject.name}}",
          "jsonataInput": null
        },
        "badge": null
      },
      "designActions": [
        {
          "value": "트렌드랭킹",
          "landingUrl": "https://www.daum.net"
        }
      ],
      "designHome": {
        "logoName": "ico_localcard.png",
        "thumbnailName": "img_logo_localcard.png"
      },
      "designDetails": {
        "backgroundImageName": null,
        "info": [
          {
            "title": "이름",
            "value": "{{$.credentialSubject.name}}"
          },
          {
            "title": "주소",
            "value": "{{$.credentialSubject.roadAddress}}"
          },
          {
            "title": "전입일",
            "value": "2020. 12. 31."
          }
        ],
        "descriptions": ["카카오톡 전자증명서로 발급되었습니다."]
      }
    }
    // ...
  ]
}

디자인 명세 생성

기본 정보

메서드	URL	인증 방식
`POST`	`https://digitalcard-partner.kakao.com/designs/definitions`	서비스 앱 어드민 키

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

디지털카드 디자인 명세를 생성합니다.

어드민 앱 키를 헤더에 담아 POST로 요청합니다. 요청 성공 시 응답은 생성한 디자인 명세 정보가 포함된 JSON 객체입니다.

이미지 파일 업로드 방법

파트너는 디자인 명세에 사용할 이미지 파일을 제휴 계약 체결 시 전달받은 연락 창구로 별도 전달해야 합니다. 이미지 파일명은 각 디자인 요소를 구체적으로 나타낼 수 있도록 지정합니다. 디자인 명세 생성 API는 톡디지털카드 시스템에 디자인 명세를 생성하는 역할만 수행하며, 전달한 이미지는 명세 생성 시 파일명을 지정해 명세에 적용할 수 있습니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O
Content-Type	`Content-Type: application/json` 요청 데이터 타입	O

본문

이름	타입	설명	필수
credentialDefinitionId	`String`	디자인 명세를 적용할 발급데이터 명세 고유 번호	O
name	`String`	디자인 명세 이름	O
designTemplateCode	`String`	디자인 명세에서 사용할 카드 템플릿 코드, 아래 중 하나 `PROFILE_A`: 프로필A `PROFILE_B`: 프로필B `HEADLINE_A`: 헤드라인A `HEADLINE_B`: 헤드라인B `HEADLINE_C`: 헤드라인C `IMAGE`: 이미지	O
cardContent	`Content`	카드 템플릿 설정	O

응답

본문

이름	타입	설명	필수
-	`DesignDefinitionResponse`	디자인 명세 정보	O

예제

요청

curl -L -X POST 'https://digitalcard-partner.kakao.com/designs/definitions' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
        "credentialDefinitionId": "1ED95FA9-997E-68FD-833D-B3E23C0895C9",
        "name": "카드 디자인 기본",
        "designTemplateCode": "HEADLINE_A",
        "cardContent": {
            "textColor": "WHITE",
            "backgroundImageName": "backgroundImageFileName.png",
            "title": {
                "value": "타이틀"
            },
            "subTitle": {
                "value": "서브 타이틀"
            }
        }
    }'

응답

디자인 명세 조회 API 응답 예제와 동일

디자인 명세 수정

기본 정보

메서드	URL	인증 방식
`PUT`	`https://digitalcard-partner.kakao.com/designs/definitions/${DESIGN_DEFINITION_ID}`	서비스 앱 어드민 키

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

디지털카드 디자인 명세를 수정합니다.

어드민 앱 키를 헤더에 담아 PUT로 요청합니다. 조회할 디자인 명세 고유 번호(ID)를 경로 변수로 포함해야 합니다.

요청 성공 시 응답은 생성한 디자인 명세 정보가 포함된 JSON 객체입니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O
Content-Type	`Content-Type: application/json` 요청 데이터 타입	O

경로 변수

이름	타입	설명	필수
ID	`String`	디자인 명세 고유 번호(`designDefinitionId`)	O

본문

이름	타입	설명	필수
name	`String`	디자인 명세 이름	O
designTemplateCode	`String`	디자인 명세에서 사용할 카드 템플릿 코드, 아래 중 하나 `PROFILE_A`: 프로필A `PROFILE_B`: 프로필B `HEADLINE_A`: 헤드라인A `HEADLINE_B`: 헤드라인B `HEADLINE_C`: 헤드라인C `IMAGE`: 이미지	O
cardContent	`Content`	카드 템플릿 설정	O

응답

본문

이름	타입	설명	필수
-	`DesignDefinitionResponse`	디자인 명세 정보	O

예제

요청

curl -L -X PUT 'https://digitalcard-partner.kakao.com/designs/definitions/${DESIGN_DEFINITION_ID}' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "카드 디자인 기본",
        "designTemplateCode": "HEADLINE_A",
        "cardContent": {
            "textColor": "WHITE",
            "backgroundImageName": "backgroundImageFileName.png",
            "title": {
                "value": "타이틀"
            },
            "subTitle": {
                "value": "서브 타이틀"
            }
        }
    }'

응답

디자인 명세 조회 API 응답 예제와 동일

기능 버튼 수정

메서드	URL	인증 방식
`PUT`	`https://digitalcard-partner.kakao.com/designs/definitions/${DESIGN_DEFINITION_ID}/design-actions`	서비스 앱 어드민 키

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

디지털카드의 기능 버튼을 수정합니다.

어드민 앱 키를 헤더에 담아 PUT로 요청합니다. 수정할 디자인 명세 고유 번호(DESIGN_DEFINITION_ID)를 경로 변수로 포함해야 합니다.

요청 성공 시 응답은 수정한 디자인 명세 정보가 포함된 JSON 객체입니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O
Content-Type	`Content-Type: application/json` 요청 데이터 타입	O

경로 변수

이름	타입	설명	필수
ID	`String`	디자인 명세 고유 번호(`designDefinitionId`)	O

본문

이름	타입	설명	필수
designActions	`Action[]`	기능 버튼 설정	O

응답

본문

이름	타입	설명	필수
-	`DesignDefinitionResponse`	디자인 명세 정보	O

예제

요청

curl -L -X PUT 'https://digitalcard-partner.kakao.com/designs/definitions/${DESIGN_DEFINITION_ID}/design-actions' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
        "designActions": [
            {
                "value": "버튼 1",
                "landingUrl": "www.daum.net"
            }
        ]
    }'

응답

디자인 명세 조회 API 응답 예제와 동일

홈 디자인 수정

메서드	URL	인증 방식
`PUT`	`https://digitalcard-partner.kakao.com/designs/definitions/${DESIGN_DEFINITION_ID}/design-home`	서비스 앱 어드민 키

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

톡디지털카드 홈 디자인을 수정합니다.

어드민 앱 키를 헤더에 담아 PUT로 요청합니다. 수정할 디자인 명세 고유 번호(DESIGN_DEFINITION_ID)를 경로 변수로 포함해야 합니다.

요청 성공 시 응답은 수정한 디자인 명세 정보가 포함된 JSON 객체입니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O
Content-Type	`Content-Type: application/json` 요청 데이터 타입	O

경로 변수

이름	타입	설명	필수
ID	`String`	디자인 명세 고유 번호(`designDefinitionId`)	O

본문

이름	타입	설명	필수
designHome	`Home`	톡디지털카드 홈 설정	O

응답

본문

이름	타입	설명	필수
-	`DesignDefinitionResponse`	디자인 명세 정보	O

예제

요청

curl -L -X PUT 'https://digitalcard-partner.kakao.com/designs/definitions/${DESIGN_DEFINITION_ID}/design-home' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
        "designHome": {
            "logoName": "logo.png",
            "thumbnailName": "thumbnail.png"
        }
    }'

응답

디자인 명세 조회 API 응답 예제와 동일

카드 정보 수정

메서드	URL	인증 방식
`PUT`	`https://digitalcard-partner.kakao.com/designs/definitions/${DESIGN_DEFINITION_ID}/design-details`	서비스 앱 어드민 키

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

디지털카드의 카드 정보를 수정합니다.

어드민 앱 키를 헤더에 담아 PUT로 요청합니다. 수정할 디자인 명세 고유 번호(DESIGN_DEFINITION_ID)를 경로 변수로 포함해야 합니다.

요청 성공 시 응답은 수정한 디자인 명세 정보가 포함된 JSON 객체입니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O
Content-Type	`Content-Type: application/json` 요청 데이터 타입	O

경로 변수

이름	타입	설명	필수
DESIGN_DEFINITION_ID	`String`	디자인 명세 고유 번호(`designDefinitionId`)	O

본문

이름	타입	설명	필수
designDetails	`Details`	카드 정보 설정	O

응답

본문

이름	타입	설명	필수
-	`DesignDefinitionResponse`	디자인 명세 정보	O

예제

요청

curl -L -X PUT 'https://digitalcard-partner.kakao.com/designs/definitions/${DESIGN_DEFINITION_ID}/design-details' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
        "designDetails": {
            "backgroundImageName": null,
            "info": [
                {
                    "title": "상세 1",
                    "value": "상세 1의 값"
                },
                {
                    "title": "상세 2",
                    "value": "상세 2의 값"
                }
            ],
            "descriptions": ["카드에 대한 설명"]
        }
    }'

응답

디자인 명세 조회 API 응답 예제와 동일

디지털카드 발급 API

발급 제안

기본 정보

메서드	URL	인증 방식
`POST`	`https://digitalcard-partner.kakao.com/issue-credential/offer`	서비스 앱 어드민 키

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

사용자에게 디지털카드 발급을 제안합니다.

사용자는 채널 메시지 또는 앱투앱 방식으로 디지털카드를 발급합니다. 발급 준비가 완료되면 설정된 웹훅(Webhook) URL로 파트너에게 발급을 요청합니다.

어드민 앱 키를 헤더에 담아 POST로 요청합니다. 디지털카드 고유 번호를 파라미터로 포함해야 합니다.

요청 성공 시 응답 헤더에 요청 접수 번호(credentialTransactionId)가 입력된 리다이렉트(Redirect) URI가 포함됩니다. 응답 본문은 요청 접수 번호가 포함된 JSON 객체입니다. 요청 실패 시 에러 코드에서 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

본문

이름	타입	설명	필수
credentialDefinitionId	`String`	발급데이터 명세 고유 번호	O
account	`Object`	사용자 식별 정보, 아래 중 하나 포함: `appUserId`: 앱에 연결된 사용자의 회원번호 `phoneNumber`:카카오톡에 가입된 전화번호(형식: `8210XXXXXXXX`) 주의: 채널 메시지 발급 방식인 경우 필수	X
sendBizMessage	`Boolean`	발급 제안 알림톡 전송 여부(기본값: `true`)	X

응답

본문

이름	타입	설명	필수
credentialTransactionId	`String`	요청 접수 번호	O

예제

요청

curl -L -X PATCH 'https://digitalcard-partner.kakao.com/issue-credential/offer' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}' \
  -d '{
        "account": {
            "phoneNumber": "821051171111"
        },
        "credentialDefinitionId": "1ed513ba-6dfb-6fac-8055-cba3246a4667",
        "sendBizMessage": true
    }'

응답

// HTTP/1.1 201 Created
{
  "credentialTransactionId": "1ed60cd4-71de-6ac1-bb8a-638a3b172337"
}

발급 제안 취소

기본 정보

메서드	URL	인증 방식
`POST`	`https://digitalcard-partner.kakao.com/issue-credential/${CREDENTIAL_TRANSACTION_ID}/cancel`	서비스 앱 어드민 키

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

사용자에게 전달한 디지털카드 발급 제안을 취소합니다.

디지털카드가 발급되기 전에만 취소 가능합니다.

어드민 앱 키를 헤더에 담아 POST로 요청합니다. 요청 URL에 경로 변수(Path variable)로 요청 접수 번호(credentialTransactionId)를 포함해야 합니다.

요청 성공 시 응답은 본문 없이 HTTP 204 상태 코드만 반환합니다. 요청 실패 시 에러 코드에서 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

경로 변수

이름	타입	설명	필수
CREDENTIAL_TRANSACTION_ID	`String`	요청 접수 번호	O

예제

요청

curl -L -X POST 'https://digitalcard-partner.kakao.com/issue-credential/1ed60cd4-71de-6ac1-bb8a-638a3b172337/cancel' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}'

응답

HTTP/1.1 204

발급 처리

기본 정보

메서드	URL	인증 방식
`POST`	`https://digitalcard-partner.kakao.com/issue-credential/${CREDENTIAL_TRANSACTION_ID}/issue`	서비스 앱 어드민 키

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

사용자에게 디지털카드를 발급합니다.

발급 전 디지털카드 발급 > 발급 제안 API 호출 후 발급 요청 웹훅(Webhook)을 받아야 합니다.

어드민 앱 키를 헤더에 담아 POST로 요청합니다. 요청 URL에 경로 변수(Path variable)로 요청 접수 번호(credentialTransactionId)를 포함해야 합니다.

요청 성공 시 응답 헤더에 요청 접수 번호가 입력된 리다이렉트(Redirect) URI가 포함됩니다. 응답 본문은 요청 접수 번호가 포함된 JSON 객체입니다. 요청 실패 시 에러 코드에서 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

경로 변수

이름	타입	설명	필수
CREDENTIAL_TRANSACTION_ID	`String`	요청 접수 번호	O

본문

이름	타입	설명	필수
account	`Object`	사용자 식별 정보, 아래 포함: `appUserId`: 사용자 회원번호	O
claims	`Object`	디지털카드 발급 정보, 디지털카드 데이터 > 생성에서 입력한 `properties`값 설정 필요	O
validStartAt	`String`	발급 일자(기본값: 발급 당일, 형식: yyyy-MM-dd'T'HH:mm:ss) 예: `2022-12-15T13:05:00`	X
validEndAt	`String`	만료 일자(기본값: 2999년 12월 31일, 형식: yyyy-MM-dd'T'HH:mm:ss) 예: `2024-12-31T23:59:59`	X

응답

헤더

이름	설명	필수
Location	`Location: /issue-credential/${CREDENTIAL_TRANSACTION_ID}` 리다이렉트 URI	O

본문

이름	타입	설명	필수
credentialTransactionId	`String`	요청 접수 번호	O
cardId	`String`	디지털카드 고유 번호	O

예제

요청

curl -L -X POST 'https://digitalcard-partner.kakao.com/issue-credential/1ed60cd4-71de-6ac1-bb8a-638a3b172337/issue' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}' \
  -d '{
        "account": {
            "appUserId": 123456
        },
        "claims": {
            "author": {
                "name": "홍길동"
            },
            "datePublished": "2022-12-06"
        }
    }'

응답

// HTTP/1.1 201 Created
// Location: /issue-credential/1ed60cd4-71de-6ac1-bb8a-638a3b172337
{
  "credentialTransactionId": "1eecfcd0-00d0-6c88-9141-459517a553e9",
  "cardId": "1eecfcd0-8402-67df-ba0f-e9cfbbcc1f57"
}

정보 수정

기본 정보

메서드	URL	인증 방식
`PUT`	`https://digitalcard-partner.kakao.com/issue-credential/cards/${CARD_ID}`	서비스 앱 어드민 키

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

사용자에게 발급된 디지털카드 정보를 수정합니다.

어드민 앱 키를 헤더에 담아 PUT으로 요청합니다. 요청 URL에 경로 변수(Path variable)로 디지털카드 고유 번호(CARD_ID)를 포함해야 합니다. 디지털카드 고유 번호는 디지털카드 발급 > 발급 처리 요청의 응답으로 반환된 값입니다. 파라미터로 사용자 식별 정보를 포함해야 합니다.

요청 성공 시 응답은 본문 없이 HTTP 204 상태 코드만 반환합니다. 요청 실패 시 에러 코드에서 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

경로 변수

이름	타입	설명	필수
CARD_ID	`String`	디지털카드 고유 번호	O

쿼리 파라미터

이름	타입	설명	필수
account	`Object`	사용자 식별 정보, 아래 포함: `appUserId`: 앱에 연결된 사용자의 회원번호	O
claims	`Object`	디지털카드 발급 정보, 디지털카드 데이터 > 생성에서 입력한 `properties`값 설정 필요	O
sendTms	`Boolean`	카드 정보 수정 알림 TMS 발송 여부(기본값: `false`)	X
reason	`String`	TMS에 표기할 카드 정보 수정 이유	X
validStartAt	`String`	발급 일자(기본값: 발급 당일, 형식: yyyy-MM-dd'T'HH:mm:ss) 예: `2022-12-15T13:05:00`	X
validEndAt	`String`	만료 일자(기본값: 2999년 12월 31일, 형식: yyyy-MM-dd'T'HH:mm:ss) 예: `2024-12-31T23:59:59`	X

예제

요청

curl -L -X PUT "https://digitalcard-partner.kakao.com/issue-credential/cards/1ED76E4F-0B7F-6DB3-9493-370976F1DB5F" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d '{
        "account": {
            "appUserId": 123456
        },
        "claims": {
            "author": {
                "name": "홍길동"
            },
            "datePublished": "2022-12-06"
        },
    "sendTms": true,
    "reason": "카드 정보 변경"
    }'

응답

HTTP/1.1 204

발급 회수

기본 정보

메서드	URL	인증 방식
`DELETE`	`https://digitalcard-partner.kakao.com/issue-credential/cards/${CARD_ID}`	서비스 앱 어드민 키

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

지원 종료

디지털카드 발급 > 발급 회수의 신규 API를 제공합니다. 신규 API는 디지털카드 고유 번호로 요청하도록 사용성이 개선되었습니다. 기존 API는 더 이상 지원하지 않습니다.

사용자에게 발급된 디지털카드를 회수합니다.

사용자가 보유한 디지털카드는 삭제됩니다.

어드민 앱 키를 헤더에 담아 DELETE로 요청합니다. 요청 URL에 경로 변수(Path variable)로 디지털카드 고유 번호(CARD_ID)를 포함해야 합니다. 디지털카드 고유 번호는 디지털카드 발급 > 발급 처리 요청의 응답으로 반환된 값입니다. 파라미터로 사용자 식별 정보를 포함해야 합니다.

요청 성공 시 응답은 본문 없이 HTTP 204 상태 코드만 반환합니다. 요청 실패 시 에러 코드에서 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

경로 변수

이름	타입	설명	필수
CARD_ID	`String`	디지털카드 고유 번호	O

쿼리 파라미터

이름	타입	설명	필수
account	`Object`	사용자 식별 정보, 아래 포함: `appUserId`: 앱에 연결된 사용자의 회원번호	O
message	`String`	사용자에게 안내될 회수 사유	X

예제

요청

curl -L -X DELETE "https://digitalcard-partner.kakao.com/issue-credential/cards/1ED76E4F-0B7F-6DB3-9493-370976F1DB5F" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d '{
        "account": {
            "appUserId": 123456
        },
    }'

응답

HTTP/1.1 204

발급 이력 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://digitalcard-partner.kakao.com/issue-credential`	서비스 앱 어드민 키

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

특정 디지털카드의 발급 이력을 확인합니다.

어드민 앱 키를 헤더에 담아 GET으로 요청합니다. 파라미터로 사용자 식별 정보를 포함해야 합니다.

요청 성공 시 응답은 발급 이력이 포함된 JSON 객체입니다. 요청 실패 시 에러 코드에서 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
appUserId	`String`	사용자 회원번호	O
id	`String`	요청 접수 번호	O
reason	`String`	발급 실패 사유, 아래 중 하나: `USER_QUIT`: 사용자 진행 중단 `ILLEGAL_CREDENTIAL_CONTENT`: 발급 정보가 유효하지 않음 `PARTNER_SYSTEM_ERROR`: 발급처 시스템 오류 `WITHDRAWN`: 발급처 회수 `USER_DELETED`: 유저 삭제	X

응답

본문

이름	타입	설명	필수
credentialDefinitionId	`String`	발급데이터 명세 고유 번호	O
appUserId	`Long`	사용자 회원번호	O
state	`String`	발급 상태, 아래 중 하나 `OFFERED`: 발급 제안중 `REQUESTED`: 발급 제안 수락 후 발급 과정 진행중 `ISSUED`: 발급 완료 `CANCELED`: 발급 제안 취소 `ABANDONED`: 발급 실패 `DELETED`: 발급 완료 후 사용자가 삭제 또는 파트너에 의해 회수됨	O
updatedAt	`String`	최근 발급 상태 변경 시각(형식: yyyy-MM-dd'T'HH:mm:ss) 예: `2024-12-31T23:59:59`	O
createdAt	`String`	발급 시각(형식: yyyy-MM-dd'T'HH:mm:ss) 예: `2024-12-31T23:59:59`	O
card	`Card`	발급 정보, `state`가 `ISSUED`인 경우에만 응답에 포함(기본값: 없음)	X

Card

이름	타입	설명	필수
cardId	`String`	디지털카드 고유 번호	O
name	`String`	디지털카드 이름	O
credentialDefinitionId	`String`	발급데이터 명세 고유 번호	X
verifiableCredential	`VerifiableCredential`	디지털카드 내용	O

VerifiableCredential

이름	타입	설명	필수
type	`List`	디지털카드 데이터 규격 이름 리스트	O
@context	`List`	W3C Verifiable Credential Contexts에 정의된 디지털카드 데이터 규격	O
credentialSubject	`Object`	디지털카드 내용	O

예제

요청

curl -L -G GET 'https://digitalcard-partner.kakao.com/issue-credential' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}' \
  -d "appUserId=${APP_USER_ID}"

요청: 특정 발급 요청 건 이력 확인

curl -L -G GET 'https://digitalcard-partner.kakao.com/issue-credential/1ed60cd4-71de-6ac1-bb8a-638a3b172337' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}' \
  -d "appUserId=${APP_USER_ID}"

응답

// HTTP/1.1 200 OK
{
  "credentialDefinitionId": "1ed513ba-6dfb-6fac-8055-cba3246a4667",
  "appUserId": 123456,
  "state": "ISSUED",
  "updatedAt": "2022-11-22T20:27:36.482866",
  "createdAt": "2022-11-22T19:29:59.455595",
  "card": {
    "cardId": "1edd812c-1520-6ffe-83cc-7d0a6f96f613",
    "name": "학생인증카드",
    "verifiableCredential": {
      "type": ["VerifiableCredential"],
      "@context": ["https://schema.org", "https://www.w3.org/2018/credentials/v1"],
      "credentialSubject": {
        "name": "value"
      }
    }
  }
}

내용 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://digitalcard-partner.kakao.com/issue-credential/cards/${CARD_ID}`	서비스 앱 어드민 키

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

발급된 디지털카드의 내용을 확인합니다.

어드민 앱 키를 헤더에 담아 GET으로 요청합니다. 요청 URL에 경로 변수(Path variable)로 디지털카드 고유 번호(cardId)를 포함해야 합니다. 파라미터로 사용자 식별 정보를 포함해야 합니다.

요청 성공 시 응답은 디지털카드 내용을 포함한 JSON 객체입니다. 요청 실패 시 에러 코드에서 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

경로 변수

이름	타입	설명	필수
CARD_ID	`String`	디지털카드 고유 번호	O

쿼리 파라미터

이름	타입	설명	필수
appUserId	`String`	사용자 회원번호	O

응답

본문

이름	타입	설명	필수
-	`Card`	발급 정보	O

예제

요청

curl -L -G GET 'https://digitalcard-partner.kakao.com/issue-credential/cards/1ed513ba-6dfb-6fac-8055-cba3246a4667' \
  -H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}' \
  -d "appUserId=${APP_USER_ID}"

응답

// HTTP/1.1 200 OK
{
  "cardId": "1edd812c-1520-6ffe-83cc-7d0a6f96f613",
  "credentialDefinitionId": "1edc976d-dbc3-64c0-8500-5f7f65a27a9b",
  "name": "학생인증카드",
  "verifiableCredential": {
    "type": ["VerifiableCredential"],
    "@context": ["https://schema.org", "https://www.w3.org/2018/credentials/v1"],
    "credentialSubject": {
      "name": "value"
    }
  }
}

파트너 정보 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://digitalcard-partner.kakao.com/partner`	서비스 앱 어드민 키

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

파트너 정보를 확인합니다.

어드민 앱 키를 헤더에 담아 GET으로 요청합니다. 요청 성공 시 응답은 파트너 정보를 포함한 JSON 객체입니다. 요청 실패 시 에러 코드에서 에러 코드로 원인을 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

응답

본문

이름	타입	설명	필수
name	`String`	파트너 이름	O
appId	`Number`	파트너의 카카오디벨로퍼스 앱 아이디	O
webhookUrl	`String`	웹훅 URL, `GET`/`POST` 모두 수신 가능 필요	X
authorization	`String`	웹훅 호출 시 인증이 필요한 경우 사용될 웹훅 헤더 토큰	X

예제

요청

curl -L -X GET "https://digitalcard-partner.kakao.com/partner" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}"

응답

// HTTP/1.1 200 OK
{
  "name": "까까오",
  "appId": 123456,
  "imgUrl": "https://t1.kakaocdn.net/zzng_static/for-fun/144.png",
  "webhookUrl": "https://partner.com/callback",
  "authorization": "",
  "state": "ACTIVE"
}

디지털카드 웹훅

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

사용자 정보 요청

기본 정보

메서드	URL	인증 방식
`GET`	`/${WEBHOOK_URL}`	파트너 인증 키

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

디지털카드 발급 과정에서 디지털카드 발급 제안 API 호출 후 발급 대상 검증이 필요한 경우, 사용자 정보를 확인하기 위해 호출합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: ${PARTNER_API_KEY}` 인증 방식, 파트너 인증 키로 인증 요청	X

경로 변수

이름	타입	설명	필수
WEBHOOK_URL	`String`	웹훅 URL	O

쿼리 파라미터

이름	타입	설명	필수
credentialTransactionId	`String`	요청 접수 번호	O
state	`String`	상태 설명, `AUTHINFO`로 고정	O

응답

본문

이름	타입	설명	필수
name	`String`	사용자 이름	X
birthDate	`String`	사용자 생년월일	X

발급 요청

기본 정보

메서드	URL	인증 방식
`POST`	`/${WEBHOOK_URL}`	파트너 인증 키

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

디지털카드 발급을 요청합니다.

디지털카드 발급 과정에서 디지털카드 발급 제안 완료 후 디지털카드 발급이 가능한 경우 호출합니다. 이후 발급처는 디지털카드 발급 처리 API로 사용자에게 디지털카드를 발급할 수 있습니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: ${PARTNER_API_KEY}` 인증 방식, 파트너 인증 키로 인증 요청	X

경로 변수

이름	타입	설명	필수
WEBHOOK_URL	`String`	웹훅 URL	O

본문

이름	타입	설명	필수
state	`String`	상태 설명, `CREDENTIAL_REQUESTED`로 고정	O
credentialTransactionId	`String`	발급요청 접수 번호	O
account	`Object`	사용자 식별 정보, 아래 포함: `appUserId`: 사용자 회원번호	O

삭제 알림

기본 정보

메서드	URL	인증 방식
`POST`	`/${WEBHOOK_URL}`	파트너 인증 키

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

사용자가 디지털카드를 삭제할 경우, 디지털카드 삭제 사실을 전달하기 위해 호출합니다.

발급처는 발급요청 접수 번호(credentialTransactionId)와 회원번호(appUserId)로 어떤 디지털카드가 삭제되었는지 파악할 수 있습니다. 발급처는 웹훅 요청에 대해 지정된 HTTP 상태 코드로 응답해야 합니다.

204: 요청 수신 성공
401: 올바르지 않은 파트너 인증 키

요청

헤더

이름	설명	필수
Authorization	`Authorization: ${PARTNER_API_KEY}` 인증 방식, 파트너 인증 키로 인증 요청	X

본문

이름	타입	설명	필수
state	`String`	디지털카드 발급 상태 `CREDENTIAL_DELETED`(디지털카드 삭제)로 고정	O
credentialTransaction	`CredentialTransaction`	발급요청 접수 번호 (예: `14ef6ae3-c371-42aa-bcba-9e3d6aaf6b25`)	O
account	`Object`	사용자 식별 정보, 아래 포함: `appUserId`: 사용자 회원번호	O

CredentialTransaction

이름	타입	설명	필수
id	`String`	발급요청 접수 번호 (예: `14ef6ae3-c371-42aa-bcba-9e3d6aaf6b25`)	O
state	`String`	요청 상태 `DELETED`로 고정	O
cardId	`String`	디지털카드 고유 번호	O

사이드 메뉴

인하우스/공동체 문서

문서 홈

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기

디지털카드 발급

디지털카드 발급 소개

발급 방식

앱 전환 방식

채널 메시지 방식

발급 과정

디지털카드 만들기

디지털카드 발급하기

디지털카드 회수하기

발급 대상 검증

연동 방법

디지털카드 데이터 API

생성

기본 정보

요청

헤더

본문

응답

헤더

본문

예제

요청

응답

단건 조회

기본 정보

요청

헤더

경로 변수

응답

본문

CredentialDefinitionResponse

예제

요청

응답

전체 조회

기본 정보

요청

헤더

응답

본문

CredentialDefinitionResponse

예제

요청

응답

수정

기본 정보

요청

헤더

경로 변수

본문

응답

헤더

본문

예제

요청

응답

디지털카드 디자인 API

디자인 명세 조회

기본 정보

요청

헤더

경로 변수

응답

본문

DesignDefinitionResponse

Content

ValueContent

TitleValueContent