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에서 App Key + App Secret 발급
설치
1. 모듈 설치
- releases 에서 최신
whmcs-x.y.z.zip을 다운로드합니다. - WHMCS 루트 디렉터리에 압축을 해제합니다. 이렇게 하면
modules/addons/captchala/가 추가됩니다. - WHMCS 관리자에서 Setup → Addon Modules 로 이동하여 CaptchaLa 를 찾고 Activate 를 클릭합니다.
2. 설정
Configure 를 클릭한 뒤:
- App Key 와 App Secret 을 붙여넣습니다.
- Widget mode 와 Theme 를 선택합니다.
- 보호할 폼을 활성화합니다.
- 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 - 이슈 / 기능 요청: 위 저장소에 등록
- 관련 문서: Web SDK · PHP 서버 SDK · API 레퍼런스