This document guides you on how to use the Kakao Sync Simple Setup popup for e-commerce platforms (E-Commerce Platform, hereinafter hosting services) that provide shopping mall hosting services.

This document includes How to use the Kakao Sync Simple Setup popup for shopping malls that adopt Kakao Sync through a hosting service, and a Development guide for the hosting service's prerequisite integration work. If you encounter issues during development or setup, see FAQ.

Adopting Kakao Sync for shopping malls based on a hosting service is available only through hosting services that have completed the prerequisite integration. Each shopping mall can apply Kakao Sync through the Simple Setup popup by referring to the hosting service's setup guide.

The following are hosting services that support the Kakao Sync Simple Setup popup and their setup guide information.

The Kakao Sync Simple Setup popup is a popup-style web page that helps shopping mall operators easily adopt Kakao Sync from the hosting service's settings menu. With the Simple Setup popup, shopping mall operators can use the following features.

• Kakao Business integrated signup
• Create a Kakao Developers app
• Create a Kakao Talk Channel
• Apply Kakao Sync

Each shopping mall operator can launch the Kakao Sync Simple Setup popup by selecting Use Kakao Sync in the hosting service's settings menu. You can complete Kakao Sync adoption with a simple three-step process, and Kakao receives basic application information from the hosting service through the Retrieve shopping mall information API to guide the procedures required for the Kakao Sync application.

After Kakao Sync adoption is completed through the Kakao Sync Simple Setup popup, you can use the Kakao Simple Signup service on that shopping mall's homepage.

A webhook feature is also provided so that shopping mall information changed in the hosting service's settings menu can be reflected in the Kakao Sync settings. With this feature, shopping mall operators can adopt Kakao Sync or change shopping mall information without visiting the Kakao platform.

Shopping mall operators can easily adopt Kakao Sync through the Kakao Sync Simple Setup popup. The Kakao Sync Simple Setup popup is available only through hosting services that have completed the prerequisite integration.

Shopping mall operators can open the Kakao Sync Simple Setup page by selecting [Use Kakao Sync] in the settings menu of the hosting service they use. After that, they can easily complete Kakao Sync adoption through a simple three-step process, and Kakao Simple Signup is applied to the shopping mall homepage immediately upon completion.

Kakao Sync Simple Setup popup integration process

Below is a detailed guide for each step. If you have questions or need help during setup, see FAQ or request 1:1 consultation with the [Contact us] button on the Simple Setup page.

This step registers the shopping mall information to which Kakao Sync will be applied. The registered shopping mall information is displayed as-is on the Kakao Simple Signup Consent screen, so make sure the shopping mall information is set correctly.

If shopping mall information is already registered, the following screen appears.

Simple Signup settings screen

[A] Select the shopping mall information to apply Kakao Sync to, then proceed to the next step.
[B] You can also create a new app by selecting the [Create new app] button. However, creating a new app is recommended only when necessary. You can operate a maximum of 10 apps with Owner permission per account.

If no shopping mall information is registered, or if you select [B] [Create new app], the following screen appears.

Create new app screen

[A] Shopping mall logo: Register the shopping mall logo according to the guide. Use the shopping mall's representative image whenever possible.
[B] Shopping mall name: Automatically filled with the name of the shopping mall you operate. You can edit the name as needed.
[C] Company name: Automatically filled with the company name (trade name, corporation, or organization name) of the shopping mall you operate. You can edit the name as needed.

This step selects the channel to display on the Kakao Simple Signup Consent screen. The selected channel information is displayed as-is on the Simple Signup Consent screen, so make sure the channel information is set correctly.

If you already operate a Kakao Talk Channel, the following screen appears.

Kakao Talk Channel settings screen

[A] Select the channel information to display on the Simple Signup Consent screen, then proceed to the next step.
[B] You can also create a new channel by selecting the [Create new channel] button. However, creating a new channel is recommended only when necessary. You can operate a maximum of 10 channels with Master permission per account.

If you do not operate a Kakao Talk Channel, or if you select [B][Create new channel], the following screen appears.

Create Kakao Talk Channel screen

[A] Profile photo: Register the shopping mall logo according to the guide. Use the shopping mall's representative image whenever possible.
[B] Channel name: Automatically filled with the name of the shopping mall you operate. You can edit the name as needed.
[C] Search ID: The unique ID of the shopping mall channel. It is used when searching for the channel, and creating the same ID is not allowed.
[D] Category: Set the category of the shopping mall channel to match the business type.

After completing Simple Signup settings and Kakao Talk Channel settings, you can apply Kakao Sync.

Check the shopping mall information, Business channel, and automatic setup details to apply Kakao Sync, then complete the Kakao Sync Simple Signup settings. Kakao Simple Signup is applied to the shopping mall homepage immediately upon completion.

Apply Kakao Sync screen

[A] This screen appears if any of birthday, shipping address, gender, age range, name, or phone number is set as optional or required collection for shopping mall signup. It is displayed based on the personal information collection items set for the shopping mall in each hosting service, and you cannot edit these items directly in the Kakao Sync Simple Setup popup.
[B] Enter the shopping mall's Privacy Policy URL to confirm the collection items. It is displayed based on the service terms URL of the shopping mall managed by each hosting service, and you cannot edit the Privacy Policy URL directly in the Kakao Sync Simple Setup popup.

Confirm Kakao Sync application details screen

[C] Check that the shopping mall information (Kakao Developers app information) and Kakao Talk Channel information to apply Kakao Sync to are correct. If the app or channel selection is wrong, select [Cancel] to go back to the previous step and edit the selection, or create a new app or channel.
[D] If there are no issues when checking the settings, select the checkbox and then select [Complete] to apply Kakao Sync to the shopping mall.

This section guides you on how to develop Kakao Sync for hosting services that provide the Kakao Sync Simple Setup popup feature.

To support Kakao Sync Simple Setup, a hosting service must implement the following features and complete the prerequisite integration development. See each item for detailed development guides.

In addition, each shopping mall needs the following features to use Kakao Simple Signup, so the hosting service must support them through the prerequisite integration so that shopping malls can use the required features.

The following is the process by which a shopping mall applies for Kakao Sync through the Kakao Sync Simple Setup popup.

Process for a shopping mall to apply for Kakao Sync through the Kakao Sync Simple Setup popup

1. The shopping mall operator requests Kakao Sync application from the hosting service's settings menu.
2. The hosting service calls the Kakao Sync Simple Setup popup.
3. Kakao requests the shopping mall's app information from the hosting service.
4. The hosting service delivers the shopping mall's app information to Kakao.
5. Kakao displays the Kakao Sync Simple Setup popup to the shopping mall operator.
6. The shopping mall operator requests Kakao Sync application by following the guidance.
7. Kakao delivers the Kakao Sync Simple Setup popup result to the hosting service.
8. Kakao delivers a webhook containing the shopping mall's Kakao Sync application review result to the hosting service server.
9. The hosting service updates the shopping mall's Kakao Sync settings information.

When supporting Kakao Sync integration, there are items that require discussion between Kakao and the hosting service. Discuss them in advance between both parties because they may affect integration policies and development work. The items that require discussion are as follows.

• Agree on shopping mall service terms tag criteria (consent processing support)
• Kakao Sync settings UI on the shopping mall admin screen, and notifications when setup is completed or canceled
• Confirm whether Kakao Account profile (nickname, profile photo) is used and how user information is collected
• Agree on policies for Connecting Information (CI)
• Kakao Sync signup and login button wording
• Shopping mall Redirect URI rules

• Policy when a required shopping mall signup value is not in the Kakao Account user information
• Account mapping policy for existing members (regular signup members, Kakao Login signup members)
• User information update policy when Kakao Account user information changes
• Policy when a shopping mall member unlinks from the shopping mall app in Kakao Developers
• Processing policy in the shopping mall app when a shopping mall member withdraws
• Use of auto-login that skips shopping mall login in the Kakao Talk in-app browser
• Select Kakao Pay as the default payment method when displaying the shopping mall order form in the Kakao Talk in-app browser

First, create a Developers app for the hosting service and request permissions from your Kakao contact. After the permissions are applied, save the site domain information for calling the Simple Setup popup in the app platform information.

When a shopping mall operator requests Kakao Sync application from the hosting service's shopping mall management menu, call the Kakao Sync Simple Setup popup using a URL in the following format.

https://sync4ecp.kakao.com/dialog/connect?appKey=${호스팅사 앱의 대표 JAVASCRIPT KEY}&storeKey=${쇼핑몰의 고유 코드 또는 ID}

storeKey is the shopping mall's unique code and is an identifier used between Kakao and the hosting service to identify a specific shopping mall. Kakao uses the storeKey value in the Kakao Sync Simple Setup popup call URL for the Kakao Sync setup result webhook.

With this popup, shopping mall operators can complete Kakao Sync preparation and setup by following Kakao's guidance. When the Kakao Sync Simple Setup popup closes, it delivers success or failure to opener with window.opener.postMessage({data}, targetOrigin).

{
  "type": "SYNC",
  "action": "connect",
  "result": "success"
}

{
  "type": "SYNC",
  "action": "connect",
  "result": "fail",
  "detail": "에러메시지"
}

Before displaying the popup, Kakao requests the target shopping mall information from the hosting service through the Retrieve shopping mall information API. The hosting service must deliver the shopping mall information registered with the hosting service to Kakao in the specified response format.

The Retrieve shopping mall information API is used for the following two purposes.

• Used to enter basic information when applying for Kakao Sync through the Kakao Sync Simple Setup popup
• Used to retrieve the shopping mall's latest Kakao Sync settings information when the Kakao Sync information change webhook is received

See below for request and response details.

https://${전자상거래플랫폼URL}/.../${storeKey}

{
  "appKey": "쇼핑몰에 연동된 REST API App key",
  "business": {
    "identificationNumber": "사업자 등록 번호(혹은 고유 번호)",
    "name": "업체명(회사명)",
    "representativeName": "대표자명",
    "category": "업태",
    "categoryItem": "종목",
    "address": {
      "zipCode": "우편번호",
      "baseAddress": "주소1",
      "detailAddress": "주소2"
    }
  },
  "siteData": {
    "name": "쇼핑몰 이름",
    "url": "쇼핑몰 대표 url",
    "image": "쇼핑몰 로고 이미지 URL"
  },
  "sync": {
    "items": [{ "type": "EMAIL", "required": true }],
    "privacyPolicyUrl": "개인정보 처리방침 URL",
    "terms": [
      {
        "title": { "ko": "서비스 약관 제목(한글)", "en": "서비스 약관 제목(영어)" },
        "url": "서비스 약관 URL",
        "tag": "서비스 약관 태그",
        "required": false
      }
    ],
    "url": ["쇼핑몰 도메인 주소(URL)"],
    "redirectUri": ["리다이렉트 URI"]
  }
}

This is a webhook that Kakao sends to the hosting service, delivering Kakao Sync application, information change, and cancellation details to the hosting service. The webhook includes the following information.

• Shopping mall's primary platform key
• Shopping mall unique code or ID
• Shopping mall's Kakao Sync information change details
• Setup result

Then, check the response code that the hosting service returns to Kakao to complete the Kakao Sync setup. Use a webhook URL agreed upon in advance between both parties.

• POST method
• Use the pre-agreed webhook URL

// method : POST
// Content-Type: application/json;charset=UTF-8
{
  "restApiKey": "쇼핑몰 앱의 대표 REST API 키",
  "jsAppKey": "쇼핑몰 앱의 대표 JavaScript 키",
  "storeKey": "쇼핑몰 고유 코드 또는 아이디",
  "data": {
    "type": "KAKAO_SYNC",
    "action": "connect", // "connect", "disconnect" 또는 "edit",
    "result": "success"
  }
}

When the shopping mall's Kakao Sync information changes due to changes in the hosting service's settings menu, the hosting service delivers a webhook to Kakao. This is a webhook that the hosting service sends to Kakao and is called in the following cases.

• Change to the shopping mall's signup collection items
• Change to the shopping mall's signup service terms
• Change to the shopping mall's domain and Redirect URI
• Cancellation of Kakao Sync setup

For the Kakao Sync information change webhook, only the information that the shopping mall's Kakao Sync settings were changed (edit) or canceled (disconnect) is delivered via the POST method. Kakao checks the detailed Kakao Sync settings changes of the shopping mall by calling the Retrieve shopping mall information API and then reflects them on the Kakao platform. The webhook must include the following information.

• Shopping mall's primary REST API key
• Shopping mall unique code or ID
• Shopping mall's Kakao Sync information change details

https://sync4ecp.kakao.com/api/v1/sync4ecp/sync/modification?appKey=${호스팅사 앱의 대표 REST API KEY}

// curl -X POST "https://sync4ecp.kakao.com/api/v1/sync4ecp/sync/modification?appKey=${호스팅사 앱의 대표 REST API KEY}"  \
  // -H "Content-Type: application/json;charset=UTF-8" \
  // -d '{
        "storeKey":　"쇼핑몰 고유 코드 또는 아이디",
        "appKey":　"쇼핑몰 앱의 REST API 키",
        "data": {
            "type": "KAKAO_SYNC",
            "action": "edit", // 또는 "disconnect",
        }
      }'

You can directly retrieve the Kakao Sync settings of a shopping mall app using the Retrieve app information API. This is not required.

Use the hosting service's app Admin key in the request header, and use the shopping mall app's REST API key or JavaScript key received through the Kakao Sync setup result webhook in the request parameter.

curl -v -G GET "https://kapi.kakao.com/v1/ecp_app?target_app_key=${TARGET_APP_KEY}" \
  -H "Authorization: KakaoAK ${ECP_APP_ADMIN_KEY}"

{
  "ecp_type": "MAKESHOP",
  "ecp_key": "ecp_test_key_12233543645",
  "ecp_on": "2020-08-14T09:06:02Z",
  "app_id": 833225,
  "app_name": "쇼핑몰 이름",
  "company": "쇼핑몰 회사명",
  "biz_registration_num": "111-12-12345",
  "website_domains": ["http://xxx.co.kr", "https://xxx.co.kr", "http://m.xxx.co.kr", "https://m.xxx.co.kr"],
  "redirect_uris": ["http://xxx.co.kr/list/API/login_kakao_sync.html", "https://xxx.co.kr/list/API/login_kakao_sync.html", "http://m.xxx.co.kr/list/API/login_kakao_sync.html", "https://m.xxx.co.kr/list/API/login_kakao_sync.html"],
  "app_keys": {
    "JAVASCRIPT_KEY": "${JAVASCRIPT_KEY}",
    "REST_API_KEY": "${REST_API_KEY}",
    "NATIVE_APP_KEY": "${NATIVE_APP_KEY}"
  },
  "app_scopes": [
    {
      "id": "profile_nickname",
      "display": "닉네임",
      "level": "required",
      "collecting": false
    },
    {
      "id": "profile_image",
      "display": "프로필 사진",
      "level": "required",
      "collecting": false
    },
    {
      "id": "legal_name",
      "display": "본인확인정보(이름)",
      "level": "required",
      "collecting": false
    },
    {
      "id": "account_email",
      "display": "카카오계정(이메일)",
      "level": "required",
      "collecting": false
    },
    {
      "id": "account_ci",
      "display": "CI(연계정보)",
      "level": "required",
      "collecting": false
    },
    {
      "id": "phone_number",
      "display": "카카오계정(전화번호)",
      "level": "required",
      "collecting": false
    },
    {
      "id": "birthday",
      "display": "생일",
      "level": "optional",
      "collecting": false
    }
  ],
  "service_terms": [
    {
      "tag": "age_2020_0218",
      "title_ko": "만 14세 이상입니다.",
      "title_en": "14 years old and older.",
      "required": true,
      "order": 10
    },
    {
      "tag": "marketing_2020_02181",
      "title_ko": "마케팅 활용 동의",
      "title_en": "marketing",
      "required": true,
      "order": 1
    },
    {
      "tag": "optional_20200616",
      "title_ko": "선택 동의 서비스 약관",
      "title_en": "optional",
      "required": false,
      "order": 4
    },
    {
      "tag": "service_2020_0218",
      "title_ko": "서비스 약관 동의",
      "title_en": "Service terms",
      "required": true,
      "order": 1
    }
  ],
  "kakao_talk_channels": [
    {
      "public_id": "_Xxxxxx",
      "name": "채널이름",
      "uuid": "@채널1"
    }
  ]
}

{ "code": -401, "msg": "appKeyType is NATIVE_APP_KEY. but expected ADMIN_KEY" }

{ "code": -401, "msg": "no authentication key!" }

{ "code": -401, "msg": "wrong appKey(${APP_KEY}) format" }

{ "code": -5, "msg": "permission denied" }

{ "code": -401, "msg": "appKey(${APP_KEY}) is not default app key" }

{ "code": -401, "msg": "appKeyType is ADMIN_KEY. but expected [NATIVE_APP_KEY, JAVASCRIPT_KEY, REST_API_KEY]" }

For frequently asked questions during Kakao Sync Simple Setup integration for hosting services, see FAQ.