更新记录

1.0.0（2026-11-14）

本版是首个可直接导入 HBuilderX 打自定义基座的完整包。

平台兼容性

uni-app

uni-app x

其他

wb-wxfacepay-uts 微信刷脸支付（Android）插件使用说明

基于微信刷脸支付官方 SDK wxfacepay-release-2.32.105.aar 的 UTS 插件，仅支持 app-android。封装人脸识别、付款码、扫码、支付结果回传及 v2.21–v2.32 新增能力。

一、这个插件做什么

它是官方微信刷脸支付 SDK 的薄封装：把 SDK 的 Java / AIDL 接口转成 uni-app 可直接 import 的 UTS 方法，回调统一成 success / fail / complete 形式，共导出 15 个方法。

插件不提供以下内容，需要你自行具备：

• 微信支付商户资质、刷脸支付权限、软件服务商接入验收
• 过检设备与设备 SN 绑定、设备端预装的人脸服务 APP
• 商户后端：rawdata 换 authinfo、micropay 下单、订单查询与结果回传
• 收银业务页面与 UI

刷脸支付是线下收银场景，普通手机无法真机验证。请先确认资质、设备、后端三者齐备再接入。

二、支持平台

CPU 架构由设备端人脸服务 APP 决定；插件自带的 AAR 是纯 Java + AIDL 客户端，不含 .so。

三、运行前提（缺一不可）

1. 设备端人脸服务 APP 已预装。SDK 通过 com.tencent.faceservice 这个 action 查找并绑定该服务；插件已在清单里声明对应的 queries，云打包时会合并进主工程。Android 11（API 30）及以上若缺少该声明，服务查询会返回空，所有接口都会失败。
2. 设备在微信支付过检设备名录内，并完成 SN 绑定。
3. 微信支付商户资质：已入驻、开通刷脸支付权限、通过软件服务商接入验收。
4. 商户后端就绪：用 getWxpayfaceRawdata 拿到的 rawdata 去换 authinfo，用 face_code 走 micropay 下单，最后调用 updateWxpayfacePayResult 回传支付结果。
5. 自定义基座：插件含 AAR、AndroidManifest.xml、config.json 变更，必须用 HBuilderX 打自定义基座并云打包，标准基座不含这些能力。
6. 不能热更新：UTS 编译为纯原生二进制，插件更新必须重新发版 App，不支持 wgt 热更新。

插件目录中已随包提供官方 AAR，无需另行下载或放置。

四、安装与导入

1. 把 uni_modules/wb-wxfacepay-uts 整个目录放进项目根目录的 uni_modules 下；导入 zip 时保持 uni_modules/wb-wxfacepay-uts/ 这一层级。
2. 确认 package.json 的 id 与目录名一致，均为 wb-wxfacepay-uts。
3. 在页面里按需 import：

import {
  getVersion, isServiceConnected,
  initWxpayface, getWxpayfaceRawdata, getWxpayfaceCode,
  updateWxpayfacePayResult, releaseWxpayface,
  enableFirewall, disableFirewall,
  startCodeScanner, stopCodeScanner,
  quitWxpayface, getWxpayfaceUserInfo, ttsSwitch, initUiParams,
} from '@/uni_modules/wb-wxfacepay-uts'

1. 打自定义基座，运行到过检设备，再云打包正式发布。

不要同时保留旧插件。旧插件 zzzili-wxfacepayzz 及同类旧原生插件自带同一个官方 AAR，两个插件一起引入会重复打包、类冲突。请在 manifest 的「App 原生插件配置」里取消勾选旧插件。

插件目录结构

uni_modules/wb-wxfacepay-uts/
├─ package.json                       插件清单与发布元数据
├─ readme.md                          本文档
├─ changelog.md                       更新记录
└─ utssdk/
   ├─ interface.uts                   对外 API 声明
   ├─ unierror.uts                   错误对象
   └─ app-android/
      ├─ index.uts                   UTS 实现层
      ├─ WxPayFaceNative.kt          Kotlin 混编层（SDK 调用）
      ├─ AndroidManifest.xml         权限与服务可见性声明
      ├─ config.json                 原生构建配置
      └─ libs/
         └─ wxfacepay-release-2.32.105.aar   官方 SDK，已随包提供

本插件不提供独立示例 APK，也不提供 H5 演示站，完整调用示例就在下一节与「六、API 一览」中，因此无需 uniCloud 的云存储或前端网页托管；本文档也没有使用任何图片，无需图床。

五、快速上手

官方业务链路：

initWxpayface                 初始化（必须最先调用）
  → getWxpayfaceRawdata       取 rawdata
  → 【商户后端】rawdata 换 authinfo
  → getWxpayfaceCode          人脸识别，拿到 face_code
  → 【商户后端】micropay 下单
  → updateWxpayfacePayResult  回传支付结果
  → releaseWxpayface          释放

console.log(getVersion())          // "2.32.105.2032105"
console.log(isServiceConnected())  // 排错首选：设备端服务是否已连上

// 1. 初始化
initWxpayface({ perform_mode: 'LOW_PERFORM' }, {
  success: (res) => console.log('init', res['return_code'], res['return_msg']),
  fail: (err) => console.log('插件层错误', err.errCode, err.errMsg),
})

// 2. 取 rawdata，交给商户后端换 authinfo
getWxpayfaceRawdata({
  success: (res) => console.log('rawdata', res['rawdata']),
})

// 3. 人脸识别（total_fee 是 string，单位【分】）
getWxpayfaceCode({
  appid: '', mch_id: '', store_id: '', out_trade_no: '',
  total_fee: '100', face_authtype: 'FACEPAY', authinfo: '', face_code_type: '1',
}, {
  success: (res) => console.log('识别结果 / 付款码', res['face_code']),
  updateResult: (res) => console.log('SDK 查单退出', res['return_code']),
})

// 4. 后端下单后回传结果
updateWxpayfacePayResult({ /* 按官方文档字段填写 */ }, {
  success: (res) => console.log('结果回传', res),
})

releaseWxpayface()

回调语义：SDK 的所有回参，包括 return_code 不等于 SUCCESS 的业务失败，一律通过 success 原样透传，由调用方读 res['return_code'] 判断。fail 只承载插件层错误（AAR 不可用、Context 缺失、数据解析失败）。SDK 的 err_code 不会被映射、不会丢字段。

getWxpayfaceCode 与 startCodeScanner 是持续回调方法，不要频繁调用；用完分别调 releaseWxpayface() / stopCodeScanner()。

六、API 一览

基础 8 个方法

新增 7 个方法

新增方法的 params 用 UTSJSONObject 原样透传给 SDK 的 Map，不预设字段，按官方文档填写即可。

getWxpayfaceCode 请求参数

total_fee 请以官方接口文档为准（单位分、string），不要沿用旧插件页面示例里的 "0.01"。

initWxpayface 可选参数

ip、port、user、passwd、proxy_type、tcp_port、perform_mode。无代理时整块不填即可；proxy_type 取值为 0 无代理、1 HttpTunnel、2 Socks5、3 Http。

七、错误码

插件层错误走 fail，号段 9030001 - 9031000：

SDK 自身的业务状态不走 fail，在 success 回参里读：

• return_code：SUCCESS / ERROR / PARAM_ERROR / SYSTEMERROR
• err_code：如 271378620（未初始化）、271378621（初始化中）

不要混用两套错误码。

八、排错顺序

1. isServiceConnected() 返回 false：优先查设备端人脸服务 APP 是否预装、是否已启动。
2. 检查 queries 声明是否合并进最终 manifest（Android 11 及以上必需）。
3. 检查微信支付资质、设备是否在过检名录、SN 是否绑定。
4. 确认打的是自定义基座、且云打包时勾选了本插件。
5. 看 HBuilderX 控制台里 [wb-wxfacepay-uts] 前缀的混编层异常日志。

九、从旧插件迁移

旧插件 zzzili-wxfacepayzz（id=5311）是 uni.requireNativePlugin 时代的原生插件，本插件是独立的 uni_modules UTS 插件，不能直接替换，但底层是同一个官方 AAR，商户后端与设备侧不用改。

// 旧
const wxfacepayzz = uni.requireNativePlugin('zzzili-wxfacepayzz')
wxfacepayzz.getWxpayfaceRawdata(function (res) { console.log(res) })

// 新
import { getWxpayfaceRawdata } from '@/uni_modules/wb-wxfacepay-uts'
getWxpayfaceRawdata({ success: (res) => console.log(res) })

8 个方法名、参数字段、SDK 回参字段全部对齐，原来判断 return_code 的逻辑可以原样保留。注意 getVersion() 返回值、total_fee 单位、最低系统（Android 5.0）这几处差异。

十、权限与隐私声明

人脸信息属于敏感个人信息。请在自己 App 的隐私政策中如实披露，并按微信支付官方说明完成合规流程。SDK 采集明细以微信支付官方文档为准。

十一、原生依赖与来源

参考链接：

• 微信刷脸支付开发文档
• 微信刷脸支付 SDK 模式页
• 软件服务商接入流程
• 旧插件页面（id=5311）

本插件仅做 SDK 封装。发布前请自行确认微信支付对官方 AAR 再分发的授权条款。

十二、更新记录

完整更新记录见插件包内 changelog.md。