> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify KYC 앱 - 신원 및 연령 인증

> Didit의 Shopify 앱으로 결제 시 신분증 인증, 연령 확인, KYC를 코드 없이 설정하세요. 전체 KYC 검사 건당 $0.33부터, 월 $10 무료, 계약 없음.

몇 분 안에 Shopify 스토어에 Didit 신분증 인증과 연령 제한을 추가하세요.
**Didit Verify** Shopify 앱은 계정, 결제, 맞춤 랜딩 페이지 등 원하는 페이지에 놓을 수 있는 테마 블록을 설치하고, 인증 세션을 서버 측에서 생성합니다. API 키는 임베디드 앱 안에만 보관되며 스토어프런트에는 노출되지 않습니다.
인증 결과는 Shopify 관리자의 앱 **인증** 탭에 바로 표시되며, 별도의 백엔드가 필요하지 않습니다. 자체 백엔드를 운영하는 판매자는 [webhook](https://docs.didit.me/ko/integration/webhooks.md)과 [Didit API](https://docs.didit.me/ko/sessions-api/retrieve-session.md)를 통해서도 결과를 받을 수 있습니다.
Shopify를 통해 수집된 인증 데이터에 접근하기 위해 Didit Business Console에 로그인할 필요는 없습니다.

## 사전 요건

* Shopify 스토어(요금제 무관)
* 워크플로가 하나 이상 있는 [Didit Console](https://business.didit.me) 계정

***

### 1단계: 앱 설치

1. 설치 링크를 엽니다:

   [[https://admin.shopify.com/oauth/install?client\_id=cafa0d15227fb59bd47470b23eae7469](https://admin.shopify.com/oauth/install?client_id=cafa0d15227fb59bd47470b23eae7469)](https://admin.shopify.com/oauth/install?client_id=cafa0d15227fb59bd47470b23eae7469)

2. 스토어를 선택합니다(스토어가 여러 개인 경우).

3. **Install**을 클릭해 스토어에 앱을 추가합니다.

> [!NOTE]
>
> 이 앱은 `read_customers` 권한 범위 하나만 요청합니다. 이 권한은 **Allow customer-approved prefill** 옵션이 활성화되고 로그인한 고객이 선택 사항인 공유 체크박스를 선택한 경우에만 세부 정보를 미리 채우고 교차 확인하는 데 사용됩니다.

***

### 2단계: Didit 자격 증명 설정

설치 후 Didit Verify가 Shopify 관리자 안에서 열립니다. **설정**을 사용해 앱을 Didit 계정에 연결하세요.

#### API 키 가져오기

1. [Didit Business Console](https://business.didit.me)에 로그인합니다.
2. 왼쪽 사이드바에서 **API 및 webhook**으로 이동합니다.
3. API 키를 복사합니다.

![Didit Business Console에서 API 키를 가져오는 방법](https://mintcdn.com/didit-0f962782/gKLcMCmiLycklBol/images/shopify-how-to-get-api-key.jpg?fit=max\&auto=format\&n=gKLcMCmiLycklBol\&q=85\&s=9027ca685cc296a400e78d320a566453)

4. Shopify 환경설정의 **Didit API Key** 필드에 API 키를 붙여 넣습니다.

#### 워크플로 ID 확인하기

1. Didit Business Console에서 **워크플로**로 이동합니다.
2. 사용할 워크플로를 선택합니다(또는 새로 만듭니다).
3. **워크플로 ID**(`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` 형식의 UUID)를 복사합니다.

![Didit Business Console에서 워크플로 ID를 가져오는 방법](https://mintcdn.com/didit-0f962782/gKLcMCmiLycklBol/images/shopify-how-to-get-workflow-id.jpg?fit=max\&auto=format\&n=gKLcMCmiLycklBol\&q=85\&s=529dc681169efc0a6cdc96d6c0e0a605)

4. **Didit Workflow ID** 필드에 워크플로 ID를 붙여 넣습니다.

#### 설정 저장하기

저장하기 전에 **데이터 보존** 아래에서 보존 기간을 선택하세요.
이 기간은 스토어에서 이루어진 기존 및 향후 인증 모두에 적용되므로, 스토어에 필요한 기간을 선택하세요.
**Save Settings**를 클릭합니다.
다음과 같은 성공 메시지가 표시됩니다:

![Shopify 설정이 저장됨](https://mintcdn.com/didit-0f962782/gKLcMCmiLycklBol/images/shopify-settings-saved-successfuly.jpg?fit=max\&auto=format\&n=gKLcMCmiLycklBol\&q=85\&s=93dcf3469f902876ae831075da75a628)

***

### 3단계: 테마에 인증 버튼 추가하기

1. Shopify 관리자에서 **Online Store** → **Themes**로 이동합니다.
2. 활성 테마의 **맞춤 설정**을 클릭합니다.
3. 인증 버튼을 표시할 페이지(예: 계정 페이지, 맞춤 페이지)로 이동합니다.
4. **섹션 추가** 또는 **Add block**을 클릭합니다.
5. **앱** 탭으로 이동합니다.
6. **Didit Verify**를 선택합니다.

인증 버튼이 테마에 표시됩니다. 버튼을 드래그하여 섹션 안에서 위치를 조정할 수 있습니다.

***

## 인증 데이터 접근

Shopify 앱 심사 요건(5.1.5)에 따라 Shopify에서 호스팅되는 흐름으로 수집한 데이터는 외부 대시보드뿐 아니라 **Shopify 관리자 또는 앱 컨텍스트 안에서** 판매자가 접근할 수 있어야 합니다.
Didit Verify 앱은 별도의 백엔드, webhook 수신기, 커스텀 UI 없이 이 요건을 기본으로 충족합니다.

### 인증 탭(기본값, 코드 없이)

Shopify 관리자에서 **앱** → **Didit Verify** → **인증**을 열면 스토어프론트를 통해 수집된 모든 인증 세션을 상태, 고객, 국가, 타임스탬프와 함께 확인할 수 있습니다. 목록은 해당 스토어 범위로 제한됩니다.
세션을 선택하면 결정 개요, 신원 필드, 개별 인증 검사, 경고, 사용 가능한 증거를 볼 수 있습니다.
Shopify 관리자를 벗어나지 않고 **설정**, **인증**, **개인정보**, **수동 검토** 사이를 이동할 수 있습니다.
설정을 저장해도 이 탭들은 계속 사용할 수 있습니다.

> [!NOTE]
>
> 인증 탭은 Shopify 관리자에서 앱을 열었을 때만 데이터를 불러옵니다. 페이지를 다시 열라는 메시지가 보이면 Shopify 관리자 사이드바에서 **앱** → **Didit Verify**로 돌아가십시오.

Didit Business Console(`business.didit.me`)은 설정(API 키, 워크플로, webhook 대상)을 위한 별도의 관리 화면입니다.
Shopify를 통해 수집된 인증 데이터를 보라고 판매자에게 안내하지 마십시오. 그렇게 해서는 Shopify의 데이터 접근 요건을 충족하지 못합니다.
Console은 초기 설정과 자격 증명 확인에만 필요합니다.

### 자체 백엔드를 운영하는 판매자용(선택 사항)

자체 백엔드가 있고 인증 데이터의 사본을 그곳에도 두고 싶다면(예: 이행 로직 트리거), Didit은 위의 인증 탭과 함께 webhook과 온디맨드 API로도 결과를 전달합니다.

**1. 인증 세션 생성**

Shopify 앱은 판매자의 Didit API 키를 사용해 서버 측에서 세션을 생성합니다. 고객은 테마 블록(모달 또는 임베디드)에서 인증 흐름을 완료합니다.

**2. webhook으로 결과 전달**

세션이 최종 상태에 도달하면 Didit은 Didit Business Console의 **API 및 웹훅**에서 설정한 대상으로 서명된 `status.updated` webhook을 보냅니다.
webhook 본문에는 `Approved`, `Declined`, `In Review`, `Abandoned` 상태에 대한 전체 [결정 객체](https://docs.didit.me/ko/integration/webhooks.md#payload-구조)가 포함됩니다. 이 객체는 `GET /v3/session/{id}/decision/`이 반환하는 것과 같은 스키마입니다.
그 밖의 최종 상태(예: `Expired`, `Kyc Expired`)는 결정 payload 없이 상태 변경만 전달됩니다. 세션 상태를 확인하려면 API를 호출하십시오.

**3. 온디맨드 조회(선택 사항)**

백엔드에서 언제든 [`GET /v3/session/{sessionId}/decision/`](https://docs.didit.me/ko/sessions-api/retrieve-session)을 호출하여 전체 결정 payload(신원 필드, 라이브니스, AML, 얼굴 대조 등)를 가져올 수 있습니다.

#### Shopify용 webhook 설정

1. [Didit Business Console](https://business.didit.me)에서 **API 및 웹훅** → **웹훅**으로 이동합니다.
2. 백엔드 endpoint를 가리키는 webhook 대상을 만듭니다(HTTPS, 공개적으로 접근 가능해야 함).
3. 최소한 `status.updated`와 `data.updated` 이벤트를 구독합니다.
4. 반환된 `secret_shared_key`를 저장하여 수신 webhook의 HMAC-SHA256 서명을 검증합니다.

전체 사양, Node.js/Python/PHP의 서명 검증 예제, 재시도 동작은 [webhook 가이드](https://docs.didit.me/ko/integration/webhooks.md)를 참고하십시오.

#### API로 세션 결정 조회하기

```bash theme={null}
curl https://verification.didit.me/v3/session/<SESSION_ID>/decision/ \
  -H "x-api-key: <YOUR_API_KEY>"
```

응답에는 `session_kind`, `status`, 그리고 모든 기능 배열(`id_verifications`, `liveness_checks`, `face_matches`, `aml_screenings` 등)이 포함됩니다. 전체 응답 스키마와 필드 참조는 [세션 조회](https://docs.didit.me/ko/sessions-api/retrieve-session.md)를 참고하십시오.

***

## 설정 옵션

### 환경설정 페이지 설정

다음 설정은 Shopify 관리자의 **앱** → **Didit Verify**에서 여는 앱 환경설정에서 구성합니다.

| 설정 | 설명 |
| - | - |
| **API 키** | Didit API 키(필수) |
| **Workflow ID** | 사용할 인증 워크플로(필수) |
| **Vendor Data** | Didit Console에서 세션을 사용자와 연결하는 방식입니다. **고객 ID**(`shopify-<customer-id>`로 전송), **Customer Email**, **Shop + Customer ID**(`<shop-domain>-<customer-id>`로 전송), **없음** 중에서 선택합니다. 고객이 로그인한 경우에만 적용됩니다. |
| **Callback URL** | 인증 후 사용자를 리디렉션할 선택 사항 URL입니다. Didit은 쿼리 파라미터로 `verificationSessionId`와 `status`를 덧붙입니다. |
| **Callback Method** | 리디렉션을 처리할 기기를 정합니다. **Default (initiator)**, **Initiator**, **Completer**, **둘 다** 중에서 선택합니다. |
| **Language** | 인증 UI 언어(자동 감지 또는 특정 언어) |
| **Require Customer Login** | 활성화하면 로그인한 고객만 인증할 수 있습니다. |
| **Allow customer-approved prefill** | 로그인한 고객의 이름, 이메일, 전화번호, 주소를 사전 입력 및 신원 확인을 위해 공유할 수 있는 선택적 체크박스를 표시합니다. 고객이 선택한 경우에만 세부 정보가 전송됩니다. |
| **Automatically delete after (days)** | 스토어가 인증 기록을 보관할 기간을 선택합니다. 선택한 기간은 이 스토어의 기존 기록과 이후 기록 모두에 적용됩니다. 삭제는 되돌릴 수 없습니다. |

### 고객 개인정보 선택

**Verification choices** 아래에서 로그인한 고객은 수동 검토를 요청하거나, 동의를 철회하고 인증 데이터 삭제를 요청할 수 있습니다.

스토어프론트 블록에는 사전 입력과 신원 확인을 위해 계정 정보를 공유하는 선택 사항인 체크박스가 있습니다.
체크하지 않으면 고객이 직접 정보를 입력할 수 있습니다.

수동 검토를 요청하면 자동 인증이 일시 중지되고 **Apps → Didit Verify → 수동 검토**에 요청이 추가됩니다.
그 요청을 처리하기 전에 고객에게 연락하여 적절한 대체 방안을 마련하십시오.
수동 검토 요청을 완료해도 인증이나 구매가 승인되지는 않습니다.

동의를 철회하면 기존 인증 링크가 즉시 중지되고, 삭제가 처리되는 동안에는 새 인증이 허용되지 않습니다.
스토어프론트는 요청을 접수했다는 사실만 확인하며, 삭제가 이미 완료되었다고 주장하지 않습니다.

## 개인정보 요청 처리

**Apps → Didit Verify → Privacy**에서 Shopify 또는 스토어프런트를 통해 접수된 고객 내보내기 및 삭제 요청을 확인할 수 있습니다.

* **고객 내보내기:** 준비된 ZIP 파일을 다운로드하고, 보안이 적용된 고객 지원 절차를 통해 전달한 후 **I have delivered this export**를 선택하십시오.
* **고객 삭제:** 고객의 스토어 관련 인증 기록, 업로드된 파일, 수동 검토 요청이 모두 삭제될 때까지 요청은 진행 중 상태로 유지됩니다.
* **조치 필요:** 고객 ID가 누락된 경우 요청에 표시된 안내에 따라 해결하십시오. 프로필에 다른 스토어 또는 다른 목적의 데이터가 포함된 경우 Didit 지원팀에 문의하십시오.

내보내기 파일에는 요청한 스토어 및 고객과 연결된 인증 기록, 업로드된 파일, 수동 검토 요청이 포함됩니다.
임시 다운로드는 7일 후 만료됩니다. 필요한 경우 **Retry after resolving**을 사용하여 새 다운로드를 준비하십시오.
다운로드한 내보내기 파일은 귀사의 고객 지원 및 데이터 보호 절차에 따라 처리해야 합니다.

**설정 → 데이터 보존**에서 보존 기간을 설정하십시오.
보존 기간이 지난 인증 데이터는 자동으로 삭제되며, 그보다 최근의 인증 데이터는 계속 이용할 수 있습니다.
스토어별 기간을 선택하지 않은 경우 애플리케이션 수준의 기존 보존 설정이 계속 적용됩니다.
보존 요청 중 조치가 필요한 항목이 있는지 **Privacy**에서 확인하십시오.

삭제 요청에 **Deleted**가 표시되면 삭제는 되돌릴 수 없으며, 삭제된 미디어는 더 이상 이용할 수 없습니다.
이미 소비된 크레딧과 별도로 관리되는 차단 목록 항목에는 영향을 주지 않습니다.

## 테마 블록 설정

다음 설정은 Didit Verify 블록을 선택했을 때 Shopify 테마 편집기에서 구성합니다.

#### 연결

| 설정 | 설명 |
| - | - |
| **Mode** | **App workflow**(권장)는 앱 설정에 저장된 워크플로를 사용합니다. **UniLink workflow**는 연결된 Didit 계정의 공개 워크플로 링크를 사용합니다. 두 모드 모두 스토어와 연결된 세션을 생성하며, 결과는 앱에서 확인할 수 있습니다. |
| **UniLink URL** | UniLink 모드에서만 사용됩니다. 앱 설정에 연결된 Didit 계정의 활성 링크를 사용하십시오. 고객은 스토어 계정에 로그인해야 합니다. |

#### 표시

| 설정 | 설명 |
| - | - |
| **Display Mode** | **Modal**은 팝업 오버레이에서 인증을 엽니다. **Embedded**는 버튼 아래에 인라인으로 인증을 표시합니다. |
| **Show close button** | 인증 모달을 닫는 X 버튼을 표시하거나 숨깁니다. |
| **Exit confirmation dialog** | 인증을 닫기 전에 사용자에게 확인을 요청합니다. |
| **Auto-close on completion** | 인증이 완료되면 모달을 자동으로 닫습니다. |
| **Debug logging** | 문제 해결을 위해 브라우저 콘솔 로그를 활성화합니다. |

#### 버튼 모양

| 설정 | 설명 |
| - | - |
| **Button text** | 버튼에 표시되는 텍스트입니다(기본값: "본인 인증하기"). |
| **Success text** | 인증이 성공한 후 표시되는 텍스트입니다(기본값: "본인 인증 완료 ✓"). |
| **Background color** | 버튼 배경색입니다. |
| **Text color** | 버튼 텍스트 색상입니다. |
| **Border radius** | 버튼 모서리의 둥근 정도입니다(0–50px). |
| **Vertical padding** | 위아래 패딩입니다(0–40px). |
| **Horizontal padding** | 왼쪽과 오른쪽 패딩입니다(0–60px). |
| **Font size** | 버튼 텍스트 크기입니다(10–32px). |

***

## 권장 설정

대부분의 스토어에는 다음 설정을 권장합니다.

* **Mode:** App workflow(앱 설정에 저장된 워크플로를 사용합니다)
* **Display Mode:** Modal(모든 환경에서 작동하며 레이아웃 문제가 없습니다)
* **Require Customer Login:** 활성화(인증을 고객 계정에 연결합니다)
* **Allow customer-approved prefill:** 활성화(고객이 스토어 정보를 공유할지 직접 선택합니다)

***

## 테스트

1. 테마를 미리 보거나 스토어를 방문하십시오.
2. Didit Verify 버튼이 있는 페이지로 이동하십시오.
3. **본인 인증하기**를 클릭하십시오.
4. 인증 과정을 완료하십시오.
5. 백엔드에서 webhook 전송을 확인하거나, [GET /v3/session/{id}/decision/](https://docs.didit.me/ko/sessions-api/retrieve-session.md)을 호출하여 인증 결과를 가져오십시오.

> [!NOTE]
>
> 샌드박스는 무료입니다(각 샌드박스 애플리케이션은 24시간마다 테스트 세션을 500개까지 생성할 수 있습니다). 따라서 전체 과정을 비용 없이 테스트할 수 있습니다. 라이브 모드에서는 무료 요금제에 매월 \$10의 크레딧이 포함됩니다.

***

## 문제 해결

### 버튼을 클릭해도 아무 일도 일어나지 않습니다

* 환경 설정에서 API 키와 Workflow ID를 저장했는지 확인하십시오.
* Workflow ID가 API 키와 같은 애플리케이션에 속하는지 확인하십시오.
* 블록 설정에서 **Debug logging**을 활성화하고, 브라우저 콘솔에서 오류를 확인하십시오.

### "Didit credentials not configured" 오류

* 이 스토어에 저장된 API 키 또는 Workflow ID가 없습니다. **앱** → **Didit Verify**를 열어 두 필드를 모두 입력한 다음 **Save Settings**를 클릭하십시오.

### "본인 인증을 하려면 로그인해야 합니다" 오류

* **Require Customer Login**이 활성화되어 있습니다(기본값). 고객은 먼저 스토어 계정에 로그인해야 합니다. 게스트 인증이 필요한 경우 앱 환경 설정에서 이 설정을 비활성화하십시오.

### 설정이 저장되지 않습니다

* "API key validation failed" - [Didit Business Console](https://business.didit.me)에서 API 키를 다시 복사하고, 불필요한 공백이 없는지 확인하십시오.
* "This workflow does not belong to your application" - Workflow ID가 API 키와 다른 Didit 애플리케이션에 속합니다. 두 값을 같은 애플리케이션에서 복사하십시오.

## 지원(24/7)

저희 팀이 원활하게 시작할 수 있도록 도와드리겠습니다.

> [card] [이메일](mailto:hello@didit.me)
>
> [hello@didit.me](mailto:hello@didit.me)로 이메일을 보내 주십시오.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.