---
title: WHMCS
---

# WHMCS

CaptchaLa 공식 WHMCS 애드온 모듈. 코드를 작성하지 않고 WHMCS 고객 영역에 CAPTCHA 검증을 추가합니다 — 로그인, 회원가입, 비밀번호 재설정, 연락처 폼, 티켓 제출, 장바구니 결제.

단순한 site-key 위젯과 달리, 모든 챌린지는 **서버에서 발급한 일회용 토큰**(재전송 방지)으로 뒷받침되며 제3자 추적기를 전혀 로드하지 않습니다.

## 보호 대상

아래 항목은 모두 모듈 설정의 개별 토글입니다 — 보호하려는 진입점만 활성화하면 됩니다.

- 로그인
- 회원가입
- 비밀번호 재설정
- 연락처 폼
- 티켓 제출
- 장바구니 결제

## 요구 사항

- WHMCS 8.x 및 9.x(8.3 및 9.0 고객 영역에서 테스트됨; `six`와 `twenty-one` 테마 모두에서, Friendly URLs 사용 여부와 무관하게 동작)
- PHP 8.0+(WHMCS 9.0 자체는 PHP 8.2+ 필요)
- CaptchaLa 계정 — [`dash.captcha.la`](https://dash.captcha.la) 에서 **App Key** + **App Secret** 발급

## 설치

### 1. 모듈 설치

1. [releases](https://github.com/Captcha-La/captchala-whmcs/releases) 에서 최신 `whmcs-x.y.z.zip` 을 다운로드합니다.
2. **WHMCS 루트** 디렉터리에 압축을 해제합니다. 이렇게 하면 `modules/addons/captchala/` 가 추가됩니다.
3. WHMCS 관리자에서 **Setup → Addon Modules** 로 이동하여 **CaptchaLa** 를 찾고 **Activate** 를 클릭합니다.

### 2. 설정

**Configure** 를 클릭한 뒤:

1. **App Key** 와 **App Secret** 을 붙여넣습니다.
2. **Widget mode** 와 **Theme** 를 선택합니다.
3. 보호할 폼을 활성화합니다.
4. **Save Changes** 를 누릅니다.

관리자 사이드바의 **CaptchaLa** 페이지를 열면 대시보드에 대한 실시간 연결 테스트를 실행할 수 있습니다.

::: tip
활성화 후 위젯이 나타나지 않으면 모듈 설정을 한 번 다시 저장하세요 — WHMCS는 모듈이 (재)활성화/저장될 때만 해당 모듈의 `hooks.php` 를 등록합니다.
:::

## 설정 항목

모든 설정은 **Setup → Addon Modules → CaptchaLa → Configure** 에 있습니다.

| 설정 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| App Key | string | — | CaptchaLa 대시보드의 공개 키. 필수. |
| App Secret | string | — | 서버 시크릿. 토큰 발급 및 검증에 사용. 필수. 브라우저로 노출되지 않습니다. |
| Widget mode | enum | `popup` | `popup`(트리거 바 → 전체 화면 챌린지), `float`(인라인 패널), `embed`(인라인 체크박스), `bind`(보이지 않음, 제출을 가로챔). |
| Theme | enum | `default` | 색상 프리셋: `default`, `dark`, `slate`, `emerald`, `amber`, `rose`. |
| Language | string | `auto` | BCP-47 코드(예: `en`, `zh`, `de`) 또는 `auto`(브라우저 추종). |
| Protect login | bool | on | 고객 영역 로그인에 챌린지를 적용. |
| Protect registration | bool | on | 신규 계정 가입에 챌린지를 적용. |
| Protect password reset | bool | on | 비밀번호 재설정 폼에 챌린지를 적용. |
| Protect contact form | bool | off | 연락처 폼에 챌린지를 적용. |
| Protect ticket submission | bool | off | 티켓 제출 최종 단계에 챌린지를 적용. |
| Protect cart checkout | bool | off | 장바구니 결제에 챌린지를 적용. |
| Skip for logged-in users | bool | on | 이미 고객 세션이 있는 방문자에게는 챌린지를 적용하지 않음. |
| Failure message | string | — | 검증 실패 시 표시되는 메시지. |

## 동작 방식

각 보호된 폼 페이지에서 모듈은 해당 폼의 action에 스코프된 새로운 **서버 토큰(`sct_`)** 을 대시보드에서 발급하고, 그에 바인딩된 위젯을 렌더링합니다. 방문자가 챌린지를 해결하면 SDK는 **일회용 패스 토큰(`pt_`)** 을 폼에 기록합니다. 제출 시 모듈은 WHMCS가 폼을 처리하기 전에 해당 `pt_` 를 서버 측에서 검증하며, 재전송과 action 불일치는 거부됩니다.

대시보드에 일시적으로 연결할 수 없는 경우, 모듈은 **페일 오픈**(제출을 통과시킴)하므로 상류의 일시적 장애로 고객 영역이 잠기는 일은 없습니다.

## FAQ

**모듈은 무료인가요?**

네. 모듈은 무료입니다. CaptchaLa 무료 플랜은 월 10,000회 검증을 포함합니다 — 더 큰 사용량이 필요한 경우에만 유료 플랜이 적용됩니다.

**WHMCS 8과 9 모두에서 동작하나요?**

네 — 8.3 및 9.0 고객 영역에서 `six`와 `twenty-one` 테마로, Friendly URLs 사용 여부와 무관하게 테스트되었습니다.

**위젯이 표시되지 않습니다.**

모듈 설정을 한 번 다시 저장하세요(Configure → Save Changes). WHMCS는 모듈이 (재)활성화/저장될 때만 `hooks.php` 를 등록합니다.

## 소스

- 모듈 저장소: [`github.com/Captcha-La/captchala-whmcs`](https://github.com/Captcha-La/captchala-whmcs)
- 이슈 / 기능 요청: 위 저장소에 등록
- 관련 문서: [Web SDK](/ko/web-sdk) · [PHP 서버 SDK](/ko/sdk/server-php) · [API 레퍼런스](/ko/api-reference)