> ## 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.

# WooCommerce 신분증 인증 플러그인: WordPress KYC

> 코드 없이 쓰는 WordPress·WooCommerce 신분증 인증, 연령 제한, KYC 플러그인. 전체 KYC 건당 $0.33부터, 월 $10 무료, 계약 없음.

모든 WordPress 사이트 또는 WooCommerce 스토어에 Didit 신분증 인증과 연령 제한을 추가하세요. 이 플러그인은 안전한 백엔드 프록시로 작동하므로 API 키가 서버에 유지되며, JavaScript를 작성하지 않고도 인증을 추가할 수 있도록 숏코드, WooCommerce 결제 게이트, 개발자 훅을 제공합니다.

## 사전 요구 사항

* WordPress 6.0 이상
* PHP 7.4 이상
* [Didit 콘솔](https://business.didit.me) 계정

## 1단계: Didit 자격 증명 가져오기

1. **[business.didit.me](https://business.didit.me)**에서 가입하거나 로그인합니다.
2. **API & Webhooks**로 이동하여 **API 키**를 복사합니다.
3. **워크플로**로 이동하여 워크플로를 만들거나 선택한 뒤 **워크플로 ID**를 복사합니다.

> [!NOTE]
>
> API 키 없이 **UniLink URL**을 사용해 인증 흐름을 미리 볼 수 있습니다.
> 콘텐츠 제한과 WooCommerce 인증 요구 사항에는 API 키와 워크플로 ID를 사용하는 **API Session** 모드를 사용하세요.
> UniLink 완료만으로는 보호된 콘텐츠에 접근하거나 주문을 승인할 수 없습니다.

## 2단계: 플러그인 설치

1. **[0.3.4 릴리스](https://github.com/didit-protocol/plugin-wordpress/releases/tag/v0.3.4)**에서 `didit-verify-0.3.4.zip`을 다운로드합니다.
2. WordPress 관리자 화면에서 **플러그인 → 새로 추가 → 플러그인 업로드**로 이동합니다.
3. 다운로드한 ZIP 파일을 선택하고 **지금 설치**를 클릭합니다.
4. **활성화**를 클릭합니다.

> [!NOTE]
>
> Didit Verify는 [WordPress.org](https://wordpress.org/plugins/didit-verify/)에도 등록되어 있습니다.
> 설치하기 전에 버전을 확인하세요. 이 문서에서 설명하는 서버 확인 기반 인증 동작을 사용하려면 0.3.4 이상이어야 합니다.
> 0.3.4부터는 승인된 인증이 나중에 거부되거나, 만료되거나, 다시 검토 상태로 돌아가면 보호된 콘텐츠에 대한 접근이 취소됩니다.
> 디렉터리에 이전 버전이 표시되어 있다면 위의 릴리스 ZIP 파일을 설치하세요.

> [!WARNING]
>
> 0.3.2 이전 버전에서 업그레이드한 경우, 서버에서 확인되지 않은 이전 승인이 있는 사용자는 보호된 콘텐츠에 접근하거나 인증이 필요한 결제를 완료하기 전에 다시 인증해야 합니다.

## 3단계: 플러그인 구성

**설정 → Didit Verify**로 이동합니다.

### 모드 선택

| 모드 | 적합한 용도 | 필요한 항목 |
| - | - | - |
| **UniLink** | 빠른 테스트 | 워크플로의 UniLink URL만 있으면 됩니다 |
| **API Session** (권장) | 실제 운영 | 워크플로 ID + API 키 |

**UniLink를 사용하는 경우:** 모드를 "UniLink"로 설정하고 URL을 붙여 넣은 뒤 저장합니다.

**API Session을 사용하는 경우:** 모드를 "API Session"으로 설정하고 워크플로 ID와 API 키를 입력한 뒤 저장합니다.

> [!NOTE]
>
> API 키는 서버에 안전하게 저장되며 방문자에게 절대 노출되지 않습니다.

### 세션 옵션 구성 (API 모드에서만)

다음은 더 세밀하게 제어할 수 있도록 제공되는 선택 설정입니다.

* **Vendor Data**: 각 인증을 Didit 대시보드의 특정 사용자와 연결하여 누가 인증했는지 추적할 수 있습니다. 기본값은 WordPress 사용자 ID(예: `wp-42`)입니다. 사용자 이메일, 사용자 지정 접두사를 선택하거나 이 기능을 끌 수도 있습니다.
* **Callback URL**: 인증이 끝난 뒤 사용자를 리디렉션할 사이트의 페이지입니다. Didit은 쿼리 매개변수로 `verificationSessionId`와 `status`를 추가합니다.
* **Callback Method**: 리디렉션을 처리할 기기를 지정합니다. `initiator`(인증을 시작한 기기), `completer`(인증을 마치는 기기), `both` 중에서 선택합니다.
* **Language**: 54개 언어 중에서 선택하거나 브라우저에서 자동으로 감지하도록 설정할 수 있습니다.

### 표시 옵션 구성

* **Display Mode**: 모달(팝업 오버레이) 또는 Embedded(페이지 안에 인라인 표시)를 선택합니다.
* **Close Button**: 모달의 X 버튼을 표시하거나 숨깁니다.
* **Exit Confirmation**: 닫을 때 "정말 닫으시겠습니까?" 대화 상자를 표시합니다.
* **Auto-close**: 인증이 완료되면 모달을 자동으로 닫습니다.
* **Debug Logging**: SDK 이벤트를 브라우저 콘솔에 기록합니다(문제 해결용).

### 버튼 꾸미기

**Button Appearance**에서 다음 항목을 변경할 수 있습니다.

* 버튼 텍스트와 성공 텍스트
* 배경색과 글자색
* 모서리 반경, 안쪽 여백, 글꼴 크기

값을 바꾸면 실시간 미리 보기에 바로 반영됩니다.

## 4단계: 사이트에 인증 추가

### WooCommerce 스토어의 경우

1. **설정 → Didit Verify → WooCommerce**에서 **Require identity verification at checkout**을 선택합니다.
2. 인증 섹션이 표시될 위치를 선택합니다.
   * 결제 페이지 상단
   * 청구 정보 입력 뒤
   * 주문 메모 뒤
   * "주문하기" 버튼 앞(권장)
3. 선택 사항으로 **Product Scope**를 고릅니다. 모든 제품(기본값), 선택한 제품만, 또는 선택한 제품을 제외한 모든 제품 중에서 고를 수 있습니다.
   제품 편집기의 **Product data → Advanced**에서 **Didit verification** 체크박스를 선택해 제품을 표시합니다.
   인증이 필요한 제품이 하나라도 장바구니에 있으면 인증이 필요합니다.
   이 범위는 결제 시 인증과 구매 후 인증 모드 모두에 적용됩니다.
4. 선택 사항으로 **설정 → Didit Verify → WooCommerce**에서 **Section Title**, **Checkout Message**, **Post-purchase Message**를 수정할 수 있습니다. 빈 필드는 기본 텍스트를 사용합니다.
5. 선택 사항으로 **Send Billing Data**를 켜면 고객의 이름, 이메일, 전화번호, 주소를 Didit에 자동으로 전송하여 사전 입력과 교차 검증에 사용합니다.

> [!NOTE]
>
> 국가 코드는 WooCommerce의 alpha-2 형식에서 Didit에 필요한 alpha-3 형식으로 자동 변환됩니다.

고객은 주문하기 전에 서버가 확인한 **Approved** 결정을 받아야 합니다.
이 규칙은 클래식 결제와 블록 결제 모두에 적용됩니다.
플러그인은 세션이 현재 고객의 것인지, 그리고 다른 주문에 이미 사용되지 않았는지 확인합니다.
세션 ID는 참조용으로 주문에 저장됩니다.

**구매 후**를 선택하면 서버가 승인을 확인할 때까지 주문은 보류 상태로 유지됩니다.
비회원 고객은 유효한 주문 키를 사용해 주문 페이지에서 인증할 수 있습니다.
서명된 상태 업데이트로 승인된 주문을 보류 상태에서 해제할 수 있도록 **설정 → Didit Verify**에 표시된 webhook URL과 비밀 값을 구성하세요.

### 모든 WordPress 페이지의 경우

아래 숏코드를 페이지나 글에 추가합니다.

```
[didit_verify]
```

**Button Appearance** 설정에 맞게 스타일이 적용된 인증 버튼이 표시됩니다.

페이지마다 텍스트를 바꿀 수 있습니다.

```
[didit_verify text="Verify Now" success_text="Done!"]
```

특정 페이지에서 임베디드 모드를 강제로 사용할 수도 있습니다.

```
[didit_verify mode="embedded"]
```

## Step 5: 인증된 사용자에게만 콘텐츠 제한하기 (선택 사항)

인증 상태에 따라 콘텐츠를 표시하거나 숨깁니다.

콘텐츠 제한은 로그인한 사용자와 API Session 모드로 확인된 승인을 요구합니다.
브라우저 콜백과 리디렉션 쿼리 매개변수로는 접근 권한이 부여되지 않습니다.

```
[didit_gate]
This content is only visible to verified users.
[/didit_gate]
```

인증되지 않은 사용자에게는 메시지와 인증 버튼이 표시됩니다. 메시지는 다음과 같이 맞춤 설정할 수 있습니다:

```
[didit_gate message="Please verify to continue."]Secret content here.[/didit_gate]
```

사이트 어디에서나 사용자의 인증 상태를 표시할 수 있습니다:

```
[didit_status]
```

로그인한 사용자에게 "Identity Verified" 또는 "Not Verified"가 표시됩니다.

## 인증 상태 확인하기

| 위치 | 방법 |
| - | - |
| **관리자 패널** | **Users → All Users**: "Didit" 열에 인증된 사용자는 ✓로 표시됩니다 |
| **WooCommerce 주문** | Didit 세션 ID가 주문 상세 정보에 표시됩니다 |
| **숏코드** | `[didit_status]`를 사용하면 모든 페이지에 상태가 표시됩니다 |

## 문제 해결

| 문제 | 해결 방법 |
| - | - |
| "Creating session..." 에서 멈춤 | **Settings → Didit Verify**에서 워크플로 ID와 API 키가 올바른지 확인하십시오 |
| 모달이 열리지 않음 | 페이지에 `[didit_verify]`가 포함되어 있는지, 또는 WooCommerce 결제 시 인증이 활성화되어 있는지 확인하십시오 |
| 인증 UI가 잘못된 언어로 표시됨 | **Session Options**에서 **Language** 설정을 변경하십시오 |
| 디버깅이 필요함 | **Display Options**에서 **Debug Logging**을 활성화한 다음 브라우저 콘솔(F12)을 열어 SDK 이벤트를 확인하십시오 |

## 보안

플러그인은 보안이 적용된 백엔드 프록시 역할을 합니다. API 키는 브라우저에 절대 전달되지 않습니다. 모든 세션 요청은 다음 항목으로 보호됩니다:

1. **CSRF nonce**: 요청은 반드시 WordPress 사이트에서 시작되어야 합니다
2. **로그인 요구 사항**: 등록된 사용자만 세션을 생성할 수 있습니다(설정 가능)
3. **속도 제한**: 사용자당 시간당 10개 세션, 게스트는 IP당 시간당 3개 세션
4. **입력 정제**: 모든 필드는 허용 목록으로 관리되며 서버 측에서 정제됩니다

세션 생성은 인증을 현재 고객 또는 주문에 연결합니다.
플러그인은 사용자 또는 주문을 승인됨으로 표시하기 전에 Didit API 또는 검증된 webhook으로 결정을 확인합니다.
인증이 필요한 경우, 일반 로그인 요구 사항이 활성화되어 있더라도 게스트 결제에서 세션을 생성할 수 있습니다.
구매 후 인증에는 유효한 주문 키도 필요합니다.

***

## 개발자용

### PHP 훅

플러그인은 다른 플러그인이나 테마가 연결할 수 있는 WordPress 액션을 실행합니다:

```php theme={null}
// When a user completes verification
add_action('didit_verification_completed', function ($user_id, $session_id, $status) {
    // Update CRM, send email, grant access, etc.
}, 10, 3);

// When a user cancels verification
add_action('didit_verification_cancelled', function ($user_id, $session_id) {
    // Log cancellation
}, 10, 2);

// When a session is created server-side
add_action('didit_session_created', function ($url, $user_id, $vendor_data) {
    // Log, notify, etc.
}, 10, 3);
```

### JavaScript 이벤트

인증이 완료되면 DOM 이벤트가 전달됩니다:

```javascript theme={null}
document.addEventListener('didit:complete', function (e) {
    console.log('Result:', e.detail); // { type, session }
});
```

### PHP에서 인증 확인하기

```php theme={null}
$is_verified = Didit_Verify::init()->is_user_verified($user_id);
```

서버 확인 절차를 포함하려면 이 헬퍼를 사용하십시오.
레거시 사용자 메타데이터나 브라우저의 `didit:complete` 이벤트만으로는 접근 권한을 부여하지 마십시오.

## 리소스

* [플러그인 소스 코드(GitHub)](https://github.com/didit-protocol/plugin-wordpress)
* [Didit API 문서](https://docs.didit.me/ko.md)
* [Didit Console](https://business.didit.me)
* [Create Session API 참조](https://docs.didit.me/ko/sessions-api/create-session.md)


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