HashPay Gateway for WHMCS v1.0.1

HashPay Gateway for WHMCS v1.0.1

这是一个可靠性与测试增强版本，重点补充支付失败路径、密钥轮换、重复通知和回调篡改测试。

更新内容

• 新增 24 项安全回归测试。
• 新增 PHP 8.2/8.3 GitHub Actions 自动检查。
• 新增 RSA-SHA256 请求签名和请求篡改测试。
• 新增 RSA-OAEP/AES-256-GCM 加密回调往返测试。
• 新增错误私钥、新密钥和旧密钥轮换测试。
• 新增密文、GCM 认证标签及算法标识篡改测试。
• 新增回调时间窗口、未来时间戳和非法时间戳测试。
• 新增金额、币种、订单状态、缺失字段及非法金额测试。
• 新增同发票重复通知和跨发票交易号冲突测试。
• 抽离统一支付准入校验，失败路径会在 addInvoicePayment() 前终止。
• 增加完整测试矩阵、沙箱测试、密钥轮换及超时重试文档。
• 移除时间与发票 ID 校验对 PHP ctype 扩展的依赖。

测试结果

24 passed, 0 failed

本地运行：

php tests/run.php

完整测试文档：

docs/TESTING.md

安装与升级

1. 下载 hashpay-whmcs9-v1.0.1.zip。
2. 解压并将 modules 目录合并上传到 WHMCS 根目录。
3. 从 v1.0.0 升级时直接覆盖模块文件，不需要修改数据库。
4. 保留现有 Merchant ID、RSA Private Key 和 API Base URL 配置。
5. 确保日志目录可写：

chmod 775 modules/gateways/hashpay/logs

宝塔环境通常还需要：

chown -R www:www modules/gateways/hashpay/logs
chmod 775 modules/gateways/hashpay/logs

Debian/Ubuntu 环境可能使用：

chown -R www-data:www-data modules/gateways/hashpay/logs
chmod 775 modules/gateways/hashpay/logs

回调地址

https://你的WHMCS域名/modules/gateways/callback/hashpay.php

回调地址必须使用公网 HTTPS。

环境要求

• WHMCS 9.x
• PHP 8.2 或 PHP 8.3
• PHP OpenSSL 扩展
• PHP cURL 扩展

文件校验

Release 附件：

hashpay-whmcs9-v1.0.1.zip

SHA-256：

746f0fa95bbf4cfa607770a7ed856b47d56ca90f3d22d8b205b57f4de9fca623

校验命令：

sha256sum hashpay-whmcs9-v1.0.1.zip

预期结果：

746f0fa95bbf4cfa607770a7ed856b47d56ca90f3d22d8b205b57f4de9fca623  hashpay-whmcs9-v1.0.1.zip

注意事项

• 建议先在测试环境执行一次成功支付、一次重复通知和一次失败路径测试。
• 密钥轮换前应处理旧订单或确认没有待重试通知。
• 不要将商户 RSA 私钥提交到 GitHub、Issue 或公开日志。
• 完整安装、测试矩阵与排错方式请查看 README 和 docs/TESTING.md。

适用于WHMCS v1.0.0的HashPay网关

HashPay Gateway for WHMCS v1.0.0

首个公开版本，为 WHMCS 9 提供 HashPay 加密货币支付网关接入。

主要功能

• 支持 WHMCS 9.x
• 支持 PHP 8.2/8.3
• 创建 HashPay 收银台订单
• 支持签名查询订单
• RSA-SHA256 API 请求签名
• RSA-OAEP SHA-256 + AES-256-GCM 加密回调
• 支付成功后自动将 WHMCS Invoice 标记为 Paid
• 校验商户 ID、时间戳、订单状态、金额和币种
• 重复通知幂等处理及重复交易保护
• 本地脱敏请求、回调和错误日志
• 无 Composer 依赖
• 可通过 HashPay 使用币安、欧易内转及多种链上支付通道

安装方法

1. 下载 Release 附件 hashpay-whmcs9-production.zip。
2. 解压后，将其中的 modules 目录合并上传至 WHMCS 根目录。
3. 在 WHMCS 后台启用 HashPay。
4. 填写 Merchant ID、RSA Private Key、HashPay API Base URL 和 API Timeout。
5. 在 HashPay 商户后台填写回调地址：

https://你的WHMCS域名/modules/gateways/callback/hashpay.php

6. 确保日志目录允许 PHP-FPM 或 Web Server 用户写入：

chmod 775 modules/gateways/hashpay/logs

如有需要，请同时将目录所有者改为实际运行 PHP-FPM 的用户。例如宝塔环境通常为 www：

chown -R www:www modules/gateways/hashpay/logs
chmod 775 modules/gateways/hashpay/logs

Debian/Ubuntu 环境可能为 www-data：

chown -R www-data:www-data modules/gateways/hashpay/logs
chmod 775 modules/gateways/hashpay/logs

环境要求

• WHMCS 9.x
• PHP 8.2 或 PHP 8.3
• PHP OpenSSL 扩展
• PHP cURL 扩展
• 公网 HTTPS 回调地址

文件校验

文件：

hashpay-whmcs9-production.zip

SHA-256：

c59a62f7b5404257fd16b6d53815a609f1ca7cabbb0128c4156b97911d256196

Linux/macOS 可使用以下命令校验：

sha256sum hashpay-whmcs9-production.zip

macOS 也可以使用：

shasum -a 256 hashpay-whmcs9-production.zip

校验结果应为：

c59a62f7b5404257fd16b6d53815a609f1ca7cabbb0128c4156b97911d256196  hashpay-whmcs9-production.zip

注意事项

• 回调地址必须使用公网 HTTPS。
• WHMCS 与 HashPay 服务器应保持时间同步。
• 不要将商户 RSA 私钥提交到 GitHub、Issue 或公开日志。
• 建议先使用小额订单完整测试创建订单、支付、加密回调和重复通知。
• 如果回调后发票没有自动入账，请检查 modules/gateways/hashpay/logs/ 下的日志及目录写入权限。

完整安装和配置文档请查看项目 README。