指南

WHMCS

WHMCS 支付网关：客户用比特币或 USDC/USDT 支付账单，直接到你的钱包，付款由签名 Webhook 记录。

Perly Pay 模块为 WHMCS 账单加上加密货币支付。客户点击用加密货币支付；账单余额变成一张 Perly Pay 账单，在 WHMCS 页面上方或单独页面中支付；签名 Webhook 把付款记录到 WHMCS。要求 WHMCS 8、PHP 8.1+ 及 curl。无需通过 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。

设置

字段	填写内容
密钥	Dashboard → Developers → API keys。`sk_test_…` 用于测试模式，`sk_live_…` 用于真实资金。
Webhook 签名密钥	`whsec_…`，来自你为这个 WHMCS 添加的 Webhook（见下文）。
付款页	浮层在账单上方打开付款窗口（pay.js）。跳转把客户带到付款页。手机上始终打开付款页本身。
币种	USD 和 EUR，或其中之一。

1
粘贴密钥
保存后点击密钥字段旁的检查连接：可以看到密钥是否可用、它的模式，以及 Perly Pay 中是否有这个 WHMCS 的 Webhook。
2
添加 Webhook
在 Dashboard → Developers → Webhooks 中添加设置里显示的地址 https://your-whmcs/modules/gateways/callback/perlypay.php，选择账单和退款事件。粘贴它的密钥并保存。
3
允许浮层
在 Dashboard → Settings 中，把 WHMCS 地址加入 Sites that may embed the checkout。否则浮层会提示在新标签页中打开付款页。

测试

使用 sk_test_… 密钥，在客户区打开一张未付账单，点击用加密货币支付。用测试币支付，或通过 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 中一行记录：发送什么、发到哪里。

只要余额不变，再次点击按钮会沿用未付的账单。每笔付款只记录一次，无论 Webhook 到达多少次，而且只针对这个 WHMCS 的账单。

退款

像平常一样在 WHMCS 中退还交易：模块会在 Perly Pay 中以客户付款时的币种发起退款（部分退款则按相同比例）。Perly Pay 会通过邮件向客户索取地址并核查；Gateway Log 会告诉你发送什么、发到哪里。你从自己的钱包发出，并把交易 ID 填入 Perly Pay — Perly Pay 从不持有资金。

上线

在 Perly Pay 中开启正式模式，并连接钱包公钥。
粘贴 sk_live_… 密钥。正式密钥和 Webhook 与测试的相互独立：在正式模式下再添加一次回调地址，并粘贴它的密钥。
在正式模式下，把 WHMCS 的 https 地址加入 Sites that may embed the checkout。
支付一张小额真实账单，然后退款。