# WHMCS

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

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

## 设置

| 字段 | 填写内容 |
| --- | --- |
| 密钥 | Dashboard → Developers → API keys。`sk_test_…` 用于[测试模式](https://pay.perly.io/docs/test-mode.md)，`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 中一行记录。不记付款。 |
| 因[核查](https://pay.perly.io/docs/screening.md)暂扣 | Gateway Log 中一行记录，附原因。在 Perly Pay 中处理。 |
| 已过期或已取消 | Gateway Log 中一行记录。再次点击按钮会创建新账单。 |
| 退款已发起、可发送、已发送、已确认 | Gateway Log 中一行记录：发送什么、发到哪里。 |

只要余额不变，再次点击按钮会沿用未付的账单。每笔付款只记录一次，无论 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 与测试的相互独立：在正式模式下再添加一次回调地址，并粘贴它的密钥。
- 在正式模式下，把 WHMCS 的 https 地址加入 **Sites that may embed the checkout**。
- 支付一张小额真实账单，然后退款。