微信小程序虚拟支付接入与 ThinkPHP 核心实现

signData 结构属性：

mode 合法值：

回调函数：

• success(res): 接口调用成功的回调函数
• fail(err): 接口调用失败的回调函数

错误码示例：

注意事项：

1. 目前只有 >= v2.19.2 的基础库支持该接口，建议开发者这样判断：当前用户的基础库版本 >= v2.19.2 时可以直接用 wx.requestVirtualPayment，小于 v2.19.2 时，用 wx.canIUse('requestVirtualPayment') 来判断接口是否可用。

示例代码

function compareVersion(_v1, _v2) {
    if (typeof _v1 !== 'string' || typeof _v2 !== 'string') return 0;
    const v1 = _v1.split('.');
    const v2 = _v2.split('.');
    const len = Math.max(v1.length, v2.length);
    while (v1.length < len) { v1.push('0'); }
    while (v2.length < len) { v2.push('0'); }
    for (let i = 0; i < len; i++) {
        const num1 = parseInt(v1[i], 10);
        const num2 = parseInt(v2[i], 10);
        if (num1 > num2) { return 1; }
        else if (num1 < num2) { return -1; }
    }
    return 0;
}

const SDKVersion = wx.getSystemInfoSync().SDKVersion;
if (compareVersion(SDKVersion, '2.19.2') >= 0 || wx.canIUse('requestVirtualPayment')) {
    wx.requestVirtualPayment({
        signData: JSON.stringify({
            offerId: '123',
            buyQuantity: 1,
            env: 0,
            currencyType: 'CNY',
            productId: 'testproductId',
            goodsPrice: 10,
            outTradeNo: 'xxxxxx',
            attach: 'testdata'
        }),
        paySig: 'd0b8bbccbe109b11549bcfd6602b08711f46600965253a949cd6a2b895152f9d',
        signature: 'd0b8bbccbe109b11549bcfd6602b08711f46600965253a949cd6a2b895152f9d',
        mode: 'short_series_goods',
        success(res) {
            console.log('requestVirtualPayment success', res);
        },
        fail({ errMsg, errCode }) {
            console.error(errMsg, errCode);
        }
    });
} else {
    console.log('当前用户的客户端不支持 wx.requestVirtualPayment');
}

ThinkPHP 核心代码实现

以下为封装好的服务类方法：

1. 查询用户代币余额

/**
 * 查询用户代币余额
 * @param string $openid 用户 openid
 * @param string $userIp 用户 IP 地址
 * @return array 微信返回的原始数据
 */
public function queryUserBalance($openid, $userIp = '') {
    $accessToken = $this->getAccessToken();
    if (!$accessToken) {
        return ['errcode' => -1, 'errmsg' => '获取 access_token 失败'];
    }
    // 生成必要的签名参数
    $timestamp = time();
    $nonce = $this->generateNonce();
    $outTradeNo = $this->generateOutTradeNo();
    // 查询余额接口也需要一个单号用于签名
    // 生成支付签名 pay_sig
    $paySig = $this->generatePaySig('/xpay/query_user_balance', [
        'offerId' => $this->config['offer_id'],
        'timestamp' => $timestamp,
        'nonce' => $nonce,
        'outTradeNo' => $outTradeNo,
    ]);
    // 生成用户态签名 signature
    $signature = $this->generateSignature($this->getSessionKey($openid), $openid, $outTradeNo);
    // 构建 URL
    $url = "https://api.weixin.qq.com/xpay/query_user_balance";
    $url .= "?access_token={$accessToken}&pay_sig={$paySig}&signature={$signature}";
    // 请求参数
    $params = [
        'openid' => $openid,
        'env' => $this->config['env'],
        'user_ip' => $userIp ?: request()->ip(), // ThinkPHP 获取客户端 IP
    ];
    $result = $this->httpPost($url, json_encode($params, JSON_UNESCAPED_UNICODE));
    // 记录日志
    Log::record("[虚拟支付] 查询余额响应：" . json_encode($result));
    return $result;
}

2. 扣减代币（代币支付）

/**
 * 扣减代币（用于代币支付道具）
 * @param string $openid 用户 openid
 * @param int $amount 扣减数量
 * @param string $orderId 业务订单号
 * @param array $payItem 物品信息 [['productid'=>'pid','unit_price'=>100,'quantity'=>1]]
 * @return array
 */
public function currencyPay($openid, $amount, $orderId, $payItem = []) {
    $accessToken = $this->getAccessToken();
    if (!$accessToken) {
        return ['errcode' => -1, 'errmsg' => '获取 access_token 失败'];
    }
    $timestamp = time();
    $nonce = $this->generateNonce();
    $outTradeNo = $this->generateOutTradeNo();
    // 用于签名的临时单号
    // 生成支付签名 pay_sig
    $paySig = $this->generatePaySig('/xpay/currency_pay', [
        'offerId' => $this->config['offer_id'],
        'timestamp' => $timestamp,
        'nonce' => $nonce,
        'outTradeNo' => $outTradeNo,
    ]);
    // 生成用户态签名 signature
    $signature = $this->generateSignature($this->getSessionKey($openid), $openid, $outTradeNo);
    $url = "https://api.weixin.qq.com/xpay/currency_pay";
    $url .= "?access_token={$accessToken}&pay_sig={$paySig}&signature={$signature}";
    $params = [
        'openid' => $openid,
        'env' => $this->config['env'],
        'user_ip' => request()->ip(),
        'amount' => $amount,
        'order_id' => $orderId, // 这里是你的业务订单号
        'payitem' => json_encode($payItem, JSON_UNESCAPED_UNICODE),
        'remark' => '代币购买道具',
    ];
    $result = $this->httpPost($url, json_encode($params, JSON_UNESCAPED_UNICODE));
    Log::record("[虚拟支付] 扣减代币响应：" . json_encode($result));
    return $result;
}

3. 查询现金订单（核心轮询接口）

/**
 * 查询现金订单状态（用于前端轮询或对账）
 * @param string $outTradeNo 你的业务订单号
 * @param string $wxOrderId 微信内部订单号（二选一）
 * @return array
 */
public function queryOrder($outTradeNo = '', $wxOrderId = '') {
    if (empty($outTradeNo) && empty($wxOrderId)) {
        return ['errcode' => -1, 'errmsg' => '订单号不能为空'];
    }
    $accessToken = $this->getAccessToken();
    if (!$accessToken) {
        return ['errcode' => -1, 'errmsg' => '获取 access_token 失败'];
    }
    // 查询订单只需要支付签名 pay_sig
    $timestamp = time();
    $nonce = $this->generateNonce();
    $paySig = $this->generatePaySig('/xpay/query_order', [
        'offerId' => $this->config['offer_id'],
        'timestamp' => $timestamp,
        'nonce' => $nonce,
        'outTradeNo' => $outTradeNo ?: $wxOrderId, // 用任一单号生成签名
    ]);
    $url = "https://api.weixin.qq.com/xpay/query_order";
    $url .= "?access_token={$accessToken}&pay_sig={$paySig}";
    $params = ['env' => $this->config['env']];
    if (!empty($outTradeNo)) {
        $params['order_id'] = $outTradeNo;
    } else {
        $params['wx_order_id'] = $wxOrderId;
    }
    $result = $this->httpPost($url, json_encode($params, JSON_UNESCAPED_UNICODE));
    // 解析并同步订单状态到本地
    if (isset($result['errcode']) && $result['errcode'] == 0 && !empty($result['order'])) {
        $this->syncOrderStatus($result['order']); // 实现本地订单状态同步
    }
    return $result;
}

4. 通知发货完成

/**
 * 手动通知微信已经发货（用于补单）
 * @param string $outTradeNo 你的业务订单号
 * @return array
 */
public function notifyProvideGoods($outTradeNo) {
    $accessToken = $this->getAccessToken();
    if (!$accessToken) {
        return ['errcode' => -1, 'errmsg' => '获取 access_token 失败'];
    }
    $timestamp = time();
    $nonce = $this->generateNonce();
    $paySig = $this->generatePaySig('/xpay/notify_provide_goods', [
        'offerId' => $this->config['offer_id'],
        'timestamp' => $timestamp,
        'nonce' => $nonce,
        'outTradeNo' => $outTradeNo,
    ]);
    $url = "https://api.weixin.qq.com/xpay/notify_provide_goods";
    $url .= "?access_token={$accessToken}&pay_sig={$paySig}";
    $params = [
        'order_id' => $outTradeNo,
        'env' => $this->config['env'],
    ];
    $result = $this->httpPost($url, json_encode($params, JSON_UNESCAPED_UNICODE));
    Log::record("[虚拟支付] 通知发货响应：" . json_encode($result));
    return $result;
}

关键注意事项

1. 签名规则：文档明确要求 支付签名 pay_sig 和 用户态签名 signature 需加在 URL 的 Query 中（如 ?access_token=xxx&pay_sig=xxx&signature=xxx），而业务参数在 POST Body 中。请严格区分。
2. 订单状态映射：微信返回的订单状态（status字段 0-10）需映射到你本地数据库的状态。特别是 2-已支付待发货 状态，是触发你发货逻辑的关键点。
3. 错误处理：注意处理文档中列出的错误码，如 -15002（outTradeNo 重复）、268490009（session_key 过期）等，并在代码中做好重试或补偿机制。
4. 环境隔离：务必使用 env 参数区分沙箱（1）和正式（0）环境。测试期间使用沙箱环境，避免真实扣费。