# WHMCS

> WHMCS の決済ゲートウェイ：顧客はビットコインや USDC/USDT で請求書を支払い、お金はあなたのウォレットに直接届き、署名付き Webhook が支払いを記録します。

Perly Pay モジュールは、WHMCS の請求書に暗号資産を追加します。顧客が **Pay with crypto**（暗号資産で支払う）を押すと、請求書の残高が Perly Pay の請求書になり、WHMCS のページの上か専用ページで支払われ、署名付き Webhook が 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 に掲載予定です。それまでは `perly-pay-whmcs.zip` を[お問い合わせ](https://pay.perly.io/ja/contact)からご依頼ください。
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** を有効にします。

## 設定

| 項目（モジュールでの表示） | 入力するもの |
| --- | --- |
| Secret key（シークレットキー） | Dashboard → Developers → API keys から。[テストモード](https://pay.perly.io/docs/test-mode.md)には `sk_test_…`、本物のお金には `sk_live_…`。 |
| Webhook signing secret（Webhook の署名シークレット） | `whsec_…`。この WHMCS 用に追加する Webhook（下記）から。 |
| Payment page（支払いページ） | **Overlay** は請求書の上に支払い画面を開きます（pay.js）。**Redirect** は顧客をそのページへ移動させます。スマートフォンでは常にページそのものが開きます。 |
| Currencies（通貨） | USD と EUR、またはどちらか一方。 |

1. **キーを貼る** — 保存し、キーの欄の **Test connection** を押します：キーが使えるか、そのモード、この WHMCS の Webhook が Perly Pay にあるかが表示されます。
2. **Webhook を追加** — Dashboard → Developers → Webhooks で、設定画面にあるアドレス `https://your-whmcs/modules/gateways/callback/perlypay.php` を、請求書と返金のイベント付きで追加します。そのシークレットを貼って保存します。
3. **Overlay を許可** — Dashboard → Settings で、WHMCS のアドレスを **Sites that may embed the checkout** に追加します。これがないと、Overlay は新しいタブで支払い画面を開くよう案内します。

## テスト

`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 に 1 行。支払いは記録しません。 |
| [確認](https://pay.perly.io/docs/screening.md)のため保留 | 理由付きで Gateway Log に 1 行。Perly Pay で判断します。 |
| 期限切れまたはキャンセル | Gateway Log に 1 行。もう一度ボタンを押すと新しい請求書ができます。 |
| 返金の開始、準備完了、送金、承認 | Gateway Log に 1 行：何をどこへ送るか。 |

残高が同じ間は、もう一度ボタンを押しても未完了の請求書を使います。Webhook が何度届いても、各支払いは一度だけ、この WHMCS の請求書にだけ記録されます。

## 返金

いつもどおり WHMCS でトランザクションを返金します：モジュールが Perly Pay で、支払われた通貨での[返金](https://pay.perly.io/docs/refunds.md)を開始します（一部返金なら同じ割合で）。Perly Pay がメールで顧客にアドレスを尋ねて確認し、Gateway Log に何をどこへ送るかが表示されます。あなたが自分のウォレットから送金し、トランザクション ID を Perly Pay に貼ります — Perly Pay がお金を預かることはありません。

## 本番開始

- Perly Pay で本番モードをオンにし、ウォレットの公開鍵を接続します。
- `sk_live_…` キーを貼ります。本番のキーと Webhook はテストとは別です：本番モードでコールバックのアドレスをもう一度追加し、そのシークレットを貼ってください。
- 本番モードの **Sites that may embed the checkout** に、WHMCS の https アドレスを追加します。
- 少額の本番の請求書を 1 件支払い、返金してみます。