# WHMCS

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

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

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

## 설치

1. **zip 받기** — 모듈은 WHMCS Marketplace에 올라가는 중입니다. 그때까지는 [문의](https://pay.perly.io/ko/contact)로 `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. [테스트 모드](https://pay.perly.io/docs/test-mode.md)는 `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에 한 줄. 결제 기록 없음. |
| [검토](https://pay.perly.io/docs/screening.md)를 위해 보류 | 이유와 함께 Gateway Log에 한 줄. Perly Pay에서 결정하세요. |
| 만료 또는 취소 | Gateway Log에 한 줄. 버튼을 다시 누르면 새 청구서가 생깁니다. |
| 환불 시작, 준비, 보냄, 확정 | Gateway Log에 한 줄: 무엇을 어디로 보낼지. |

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

## 환불

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

## 출시

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