WHMCS 接入微信支付完整教程

一、问题背景与痛点

在国内运营 IDC、主机或数字商品销售时，WHMCS 是主流的自动化计费系统。然而，WHMCS 官方原生并不支持微信支付，且市面上多数海外第三方插件存在水土不服、接口老旧（仍在使用已废弃的 APIv2）等问题。许多国内站长在寻找 WHMCS 接入微信支付完整教程 时，常因 API 拦截、回调失败、证书配置错误等痛点卡壳。微码宝（weimabao.net）基于多年本土化开发经验，为您梳理了这套基于最新 APIv3 标准的实操方案。

二、核心解决步骤

1. 资质与域名准备

微信支付要求商户必须具备企业资质，且回调域名必须完成 ICP 备案并配置有效的 SSL 证书（HTTPS）。

1. 获取适配网关插件

前往微码宝（weimabao.net）下载基于 APIv3 开发的 WHMCS 微信支付网关插件，支持 Native（扫码）、JSAPI 及 H5 支付场景。

1. 配置微信商户平台

登录微信商户平台，在“账户中心 -> API安全”中设置 APIv3 密钥（32位字符串），并下载 API 证书（包含 apiclient_cert.pem 和 apiclient_key.pem）。

1. 上传并激活插件

将插件文件上传至 WHMCS 根目录的 /modules/gateways/ 文件夹。进入 WHMCS 后台“设置 -> 支付网关”，激活微信支付模块，填入商户号（MchID）、AppID 及 APIv3 密钥。

1. 配置回调与证书路径

在插件设置中，将证书绝对路径指向服务器上的 .pem 文件。在微信商户后台的“开发配置”中，将支付回调 URL 设置为：https://yourdomain.com/modules/gateways/callback/wechatpay.php。

三、关键代码片段与配置说明

在回调处理文件 wechatpay.php 中，核心逻辑在于验证微信签名并更新账单状态。以下是关键的验签与订单激活代码片段：

// 引入微信支付 SDK 与 WHMCS 核心文件
require_once __DIR__ . '/../../../init.php';
require_once __DIR__ . '/../../../includes/gatewayfunctions.php';
require_once __DIR__ . '/../../../includes/invoicefunctions.php';

// 获取微信支付回调数据
$content = file_get_contents("php://input");
$data = json_decode($content, true);
$headers = getallheaders();

// 验证 APIv3 签名 (核心安全校验)
$verified = WechatPayValidator($headers, $content, $gateway_params['api_v3_key']);

if ($verified && $data['trade_state'] === 'SUCCESS') {
    $invoiceId = $data['attach']; // 获取附加数据中的 WHMCS 订单号
    $transactionId = $data['transaction_id'];
    $amount = $data['amount']['total'] / 100; // 微信金额单位为分，需除以100

    // 验证账单金额并激活
    $invoiceId = checkCbInvoiceID($invoiceId, 'WeChat Pay');
    checkCbTransID($transactionId);
    addInvoicePayment($invoiceId, $transactionId, $amount, 0, 'wechatpay');
    
    // 返回成功应答给微信
    echo json_encode(['code' => 'SUCCESS', 'message' => '成功']);
} else {
    echo json_encode(['code' => 'FAIL', 'message' => '验签失败']);
}

配置说明：务必确保服务器时区设置为 Asia/Shanghai，否则时间戳校验会报错。证书文件权限需设置为 644，目录权限为 755。

四、常见报错与排错指南（FAQ）

Q1：支付成功，但 WHMCS 订单未自动激活（回调失败）？ 排错：这是国内站长最常遇到的问题。首先检查域名是否已备案，未备案域名会被微信拦截回调；其次，检查服务器防火墙（如安全狗、宝塔防火墙）是否拦截了微信服务器的 IP 段；最后，使用 Postman 或 curl 测试回调 URL 是否返回 500 或 403 错误。

Q2：提示“签名错误”或“商户号不存在”？ 排错：确认使用的是 APIv3 密钥而非 v2 的 API 密钥。检查商户号（MchID）是否拼写错误，或 AppID 与商户号是否未进行绑定关联。

Q3：提示“缺少证书”或 cURL error 58/60？ 排错：检查 .pem 证书文件的绝对路径是否正确。如果是 cURL 60 错误，通常是服务器缺少 CA 根证书，需在 php.ini 中配置 curl.cainfo 路径，或在代码中临时关闭 SSL peer 验证（不推荐用于生产环境）。

五、总结与安全建议

完成上述步骤，您的 WHMCS 系统即可完美支持微信自动化收款。支付网关是系统的资金咽喉，安全不容忽视。建议定期在微信商户平台轮换 APIv3 密钥，并在服务器端限制仅允许微信官方 IP 段访问回调接口。如需获取最新的安全补丁或高级插件授权，欢迎访问微码宝（weimabao.net）获取优先技术支持。

打开 MD 链接