ガイド

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 が同梱されています。

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 を有効にします。

設定

項目（モジュールでの表示）	入力するもの
Secret key（シークレットキー）	Dashboard → Developers → API keys から。テストモードには `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 行。支払いは記録しません。
確認のため保留	理由付きで Gateway Log に 1 行。Perly Pay で判断します。
期限切れまたはキャンセル	Gateway Log に 1 行。もう一度ボタンを押すと新しい請求書ができます。
返金の開始、準備完了、送金、承認	Gateway Log に 1 行：何をどこへ送るか。

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

返金

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

本番開始

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