가이드

WHMCS

WHMCS용 결제 게이트웨이: 고객이 비트코인이나 USDC/USDT로 청구서를 내 지갑에 바로 결제하고, 서명된 웹훅이 결제를 기록합니다.

Perly Pay 모듈이 WHMCS 청구서에 암호화폐를 더합니다. 고객이 Pay with crypto(암호화폐로 결제)를 누르면 청구서 잔액이 Perly Pay 청구서가 되고, WHMCS 페이지 위나 별도 페이지에서 결제하며, 서명된 웹훅이 WHMCS에 결제를 기록합니다. WHMCS 8, curl이 있는 PHP 8.1+. Composer로 설치할 것은 없습니다: PHP SDK가 이미 들어 있습니다.

Perly Pay는 USD나 EUR로 청구합니다. 다른 통화의 고객을 위해 게이트웨이의 Convert To For Processing에서 USD나 EUR를 고르세요. 결제는 여전히 청구서 자체의 통화로 기록됩니다. 설정하지 않으면 그런 고객에게는 다른 결제 수단을 고르라는 안내가 보입니다.

설치

1
zip 받기
모듈은 WHMCS Marketplace에 올라가는 중입니다. 그때까지는 문의로 perly-pay-whmcs.zip을 요청하세요.
2
업로드
WHMCS 폴더 위에 압축을 푸세요. modules/gateways/perlypay.php, modules/gateways/callback/perlypay.php, modules/gateways/perlypay/가 추가됩니다.
3
활성화
Configuration → Apps & Integrations → Payment Gateways(또는 Setup → Payment Gateways)에서 Perly Pay를 켜세요.

설정

Setting(설정)	넣을 것
Secret key(비밀 키)	Dashboard → Developers → API keys. 테스트 모드는 `sk_test_…`, 실제 돈은 `sk_live_…`.
Webhook signing secret(웹훅 서명 비밀 값)	`whsec_…`, 이 WHMCS용으로 추가할 웹훅에서(아래).
Payment page(결제 페이지)	Overlay(오버레이)는 청구서 위에 결제창을 엽니다(pay.js). Redirect(이동)는 고객을 결제 페이지로 보냅니다. 휴대폰에서는 항상 페이지가 열립니다.
Currencies(통화)	USD와 EUR, 또는 그중 하나.

1
키 붙여 넣기
저장한 뒤 키 필드의 Test connection(연결 확인)을 누르세요: 키가 작동하는지, 모드, 그리고 이 WHMCS의 웹훅이 Perly Pay에 있는지 보여 줍니다.
2
웹훅 추가
Dashboard → Developers → Webhooks에서 설정에 나온 URL https://your-whmcs/modules/gateways/callback/perlypay.php를 청구서·환불 이벤트와 함께 추가하세요. 그 비밀 값을 붙여 넣고 저장하세요.
3
오버레이 허용
Dashboard → Settings의 Sites that may embed the checkout에 WHMCS 주소를 추가하세요. 그러지 않으면 오버레이가 새 탭에서 결제를 열라고 제안합니다.

테스트

sk_test_… 키로 고객 영역에서 미결제 청구서를 열고 Pay with crypto를 누르세요. 테스트 코인으로, 또는 API로 결제하세요 — 청구서 ID는 결제 페이지에 있습니다:

bash

curl -X POST https://pay.perly.io/api/v1/invoices/inv_…/simulate \
  -H "Authorization: Bearer $PERLY_PAY_SECRET_KEY" -H "Content-Type: application/json" -d '{}'

몇 초 안에 WHMCS 청구서가 Paid가 됩니다. Billing → Gateway Log에 네트워크, 금액, 트랜잭션 링크가 나옵니다.

청구서가 결제를 따라가는 방식

Perly Pay에서	WHMCS에서
결제됨, 송금자 검사 완료(`invoice.fulfilled`)	고객에게 청구한 금액으로, 청구서 통화로, Perly Pay 결제 ID(`pay_…`)와 함께 결제 기록. WHMCS가 청구서를 Paid로 표시하고 나머지는 평소처럼 처리합니다.
감지됨, 일부 결제, 결제됐지만 아직 검사 중	Gateway Log에 한 줄. 결제 기록 없음.
검토를 위해 보류	이유와 함께 Gateway Log에 한 줄. Perly Pay에서 결정하세요.
만료 또는 취소	Gateway Log에 한 줄. 버튼을 다시 누르면 새 청구서가 생깁니다.
환불 시작, 준비, 보냄, 확정	Gateway Log에 한 줄: 무엇을 어디로 보낼지.

잔액이 같은 동안에는 버튼을 다시 눌러도 열린 청구서를 씁니다. 웹훅이 몇 번 오든 결제는 한 번만, 이 WHMCS의 청구서에만 기록됩니다.

환불

WHMCS에서 평소처럼 트랜잭션을 환불하세요: 모듈이 결제한 코인으로 Perly Pay에 환불을 엽니다(부분 환불이면 같은 비율로). Perly Pay가 이메일로 고객에게 주소를 받아 검사하고, Gateway Log에 무엇을 어디로 보낼지 나옵니다. 내 지갑에서 보내고 Perly Pay에 트랜잭션 ID를 붙여 넣으세요 — Perly Pay는 돈을 절대 보관하지 않습니다.

출시

Perly Pay에서 라이브 모드를 켜고 지갑의 공개 키를 연결하세요.
sk_live_… 키를 붙여 넣으세요. 라이브 키와 웹훅은 테스트와 별개입니다: 라이브 모드에서 콜백 URL을 다시 추가하고 그 비밀 값을 붙여 넣으세요.
라이브 모드의 Sites that may embed the checkout에 WHMCS의 https 주소를 추가하세요.
작은 실제 청구서 하나를 결제하고 환불해 보세요.