前端SDK Android文档

一、版本更新

1.0 文档修订记录

版本发布列表
版本号 发布日期 新增功能 优化内容
1.0.2 2018.6.14 人脸应用发布
1.0.4 2018.6.22
1.0.6 2018.6.28
1.0.8 2018.7.9 1.支持商户传入手机号
2.返回,重新识别,协议添加状态
1.数据上报混淆问题
2.TBS遍历修复
3.添加鉴权失败提示
4.web页内存问题
1.1.0 2018.8.1 1.支持动态升级及静默安装
2.支持网络代理
3.异常上报及数据上报统计
4.支持订单上报
1.新增采集白屏(摄像头异常)提示及上报
2.协议统一新签名方式
3.强校验SN
4.部分代码重构
1.1.2 2018.8.17 1.细化优图监权上报
2.支持横屏设备
3.返回是否使用传入手机号获取ft标志位
1.其他BugFix
2.SO精简包大小
1.1.3 2018.8.17 1.917特供版本,仅用于登录
1.14.288 2018.9.20 1.新增1:N用户识别功能
2.横屏适配
3.微信侧支付成功页
4.小摄像头适配
1.14.290 2018.10.12 1.更新华捷摄像头SDK,优化白屏问题
1.14.294 2018.10.24 1.修复成功页支付成功文字换行问题
2.修复支付成功页超时后,下次无法支付问题
1.14.296 2018.10.29 1.成功页点完成后给商户回调
2.升级versioncode
1.16.288 2018.11.2 1.运营位图片功能
2.错误码自查界面
1.客户端一键上传Log、后台指令下发上传Log
2.优图小屏UI适配
3.成功页优先考虑商户支付结果
1.16.290 2018.11.6 1.修复摄像头异常
2.修复crash问题
1.16.306 2018.11.22 1.优化支付成功页逻辑
2.修复crash问题
1.16.308 2018.11.26 1.图片上传失败返回扫码支付回调
1.18.288 2018.12.12 1.人脸识别深色版
2.人脸支付返回是否未成年功能
3.人脸支付延迟支付场景
1.人脸识别授权页体验优化
2.人脸支付成功页弱化功能
3.设置页网络检测工具
4.设置页摄像头检测工具
5.设置页运行环境工具
1.18.290 2018.12.14 1.修复首次开通未返回未成年的标志位的问题
2.摄像头失败增加重试
3.crash堆栈打到xlog
1.18.296 2018.12.18 1.修复1:N识别错误后卡住的问题
2.更新华捷sdk,修复摄像头卡住问题
1.18.300 2018.12.24 1.更新华捷sdk,修复crash问题
1.19.201 2018.12.29 1. lpos扫码功能用于给小蚁测试lpos功能
1.20.288 2019.3.1 1.LPos人脸支付
2.LPos扫码支付
1.成功页UI优化
2.分辨率适配优化
3.动画流畅性优化
1.20.290 2019.3.8 1.回滚到优图旧模型
2.修复1:N授权页连续点击触发多次请求的问题
1.22.288 2019.3.8 1. 1:N支付功能 1.LPOS成功页文案修改
2.扫码去掉成功页
3.扫码和刷脸成功均只有提示音滴一声
1.22.290 2019.3.13 1. 华捷sdk更新
2. 彩色图深度图同步策略更新
3. 修复4G网络无法使用网络检测工具的问题
1.22.292 2019.3.22 1. 电子海报功能 1. rawdata增加位置信息
1.20.292 2019.3.26 1.修复优图两次识别结果相同的问题
1.22.294 2019.3.25 1.修复优图两次识别结果相同的问题
2.关闭被扫支付条码识别功能
3.新增电子海报客户端产品上报
1.22.296 2019.3.29 1.增加设置页增加是否支付条码扫码开关
1.22.298 2019.4.5 1、优图图像撕裂问题
2、优化摄像头切换曝光模式导致图片过曝
3、运营浮窗广告功能问题修复
1、支付成功页 2、扫条码开关 3、日志增加音量打印
1.20.294 2019.4.11 1、修复优图两次识别结果相同的问题
1.22.300 2019.4.12 一、成功页
1)增加支付成功页
2)等待支付结果流程拆分
3)优化视觉交互
二、1:N支付
1)等待扣款码时增加动画
一、crash修复
1)腾讯地图sdk问题
2)获取authcode空指针
3)统计上报多线程并发
二、优化多次扣款码问题
三、完善统计上报
1.24.288 2019.4.15 1、红包核销需求
2、红包卡包需求
3、红包上报需求
1、红包运营广告需求
2、优化运营位上报逻辑
3、运营位下发适配界面优化
4、网络检测优化
5、crash修复
1.24.290 2019.4.17 1、修复红包文案中没有金额符号问题
2、修复部分横屏机器红包动画兼容性问题
1.24.292 2019.4.18 1、人脸识别优选线程退出异常
2、修复Android6.x系统bug导致标准API调用行为异常
1.24.294 2019.4.23 一、核身错误弹框按钮逻辑优化
二、crash问题修复
1)修复红包动画判空crash
2)修复发送请求判空crash
3)修复输入手机号数据越界crash
1.26.288 2019.4.25 1、青蛙会员功能 一、集成双向通信SDK
二、会员特性开发
三、会员成功页
四、后台下发控制收银/会员模式
1.26.292 2019.5.19 1、青蛙会员功能
2、扫描核身功能
3、新增SDK返回扣款码模式
成功页重构
1.26.294 2019.5.21 1、修复风险核身流程通过后,未返回subopenid,导致商户app Crash的问题
1.26.296 2019.5.30 1、修复人脸终端启动后Crash的问题
2、修复人脸终端支付成功页关闭弹窗Crash的问题
3、优化摄像头打开失败的问题
1.26.298 2019.5.31 1、修复青蛙设备刷脸支付未上报的问题
1.28.266 2019.5.29 1、支付成功页新增关注公众号功能
2、青蛙电子海报新增官方默认、官方活动海报轮播功能
3、新增扫码支付付款码透传扫码盒子能力
1、人脸优选加入质量分评估
2、性能监控上报
1.28.268 2019.6.7 1、修复成功页上报问题
2、修复reportOrder crash问题
1.28.268 2019.6.29 优化文档结构,以及相关说明
2.0 2019.8.19 1.新增实名认证交互流程
2.新增实名认证接口 getWxpayAuth
3.人脸识别getWxpayfaceCode 新增返回用户身份信息查询凭证参数(face_sid)
2.12 2019.11.8 1.新增会员识别获取unionid逻辑
2.去掉会员识别是否授权参数
3.人脸支付新增快捷支付模式
2.12 2020.2.13 1、新增支持TCP代理
2.13 2020.2.13 1、更新实名授权流程 1、用户刷脸返回face_sid给商户后,商户判断不管是否需要实名授权都要调用 getWxpayAuth 接口通知人脸识别app
2、所有接口返回FAIL时可能会带有对应的二级错误码err_code
3、刷脸服务自动断线重连,对应的initWxpayface一定有回调

1.1 版本升级指引

  1. 人脸识别app1.14版本增加了微信支付成功页,支付时自动关闭人脸识别app的逻辑去掉,先展示微信支付的成功页,展示完毕后人脸识别app会主动关闭,触发回调,再展示商户的支付成功页。相关接口见updateWxpayfacePayResult。
  2. 自1.16版本增加了运营位展示,相关接口见updateWxpayfaceBannerState。

1.2 参数表中的“必填”栏取值说明

取值 解释
是 / Y 表示该参数必填
否 / N 表示该参数非必填,可以为空
S 表示该参数仅在错误码为SUCCESS时填写

公共错误码

所有接口的return_code参数,都可能返回的公共错误码。

错误码 描述 解决方案
SUCCESS 接口成功
ERROR 接口失败 展示错误原因(该请求无法通过重试解决)
PARAM_ERROR 参数错误 参照错误提示
SYSTEMERROR 接口返回错误 系统异常,可重试该请求

二级错误码

所有接口都可能返回二级错误码err_code参数,根据相应参数商户可以处理异常。

错误码 描述 解决方案
271378620 刷脸服务未初始化 立即调用initWxpayface初始化服务
271378621 刷脸服务初始化中 延后500ms调用initWxpayface初始化服务

二、各场景交互流程

1.0 人脸凭证的交互流程

1.1 流程功能介绍

该流程通过识别用户人脸、手机号,获取人脸凭证(face_code),该人脸凭证具有较高的安全等级,可用于支付。

1.2 名词解释

**人脸授权:**通过人脸识别,返回微信用户信息(openid, face_code)。

face_code:人脸凭证。常用于人脸支付,作为订单的支付凭证。

1.3 人脸凭证时序图

sequenceDiagram participant A as 商户APP participant B as 微信人脸sdk participant C as 商户server participant D as 微信支付后台API A ->> B: 1. 程序启动时初始化 initWxpayface B -->> A: doInitWxpayface(返回初始化结果) A ->> B: 2. 获取数据 getWxpayfaceRawdata B -->> A: doGetWxpayfaceRawdata(返回rawdata) A ->> C:3.获取SDK调用凭证 C->>D:3.get_wxpayface_authinfo(rawdata) D-->>C:返回authinfo C -->> A:返回authinfo A ->> B: 4. 进行人脸识别 getWxpayfaceCode A ->> B: 启动人脸识别activity activate B B ->> B: 进行人脸识别 B ->> B: 完成人脸识别 B -->> A: 回调返回人脸识别结果(face_code, openid) B -->> A: doWxPayfaceCodeCallback(返回人脸识别结果) note over A,D:进行刷脸支付,参见3.0人脸支付时序图 A ->> B: 5. 更新支付结果updateWxpayfacePayResult(callback) B->>B:用户确认支付结果 A ->> B: 关闭人脸应用界面 deactivate B B -->> A: doUpdatePayResultCallBack(界面关闭,触发回调) A ->> A: 程序退出(...) A ->> B: 6. 释放资源 releaseWxpayface

注:

  1. 初始化 initWxpayface, 只需要在程序启动时调用;
  2. 释放资源 releaseWxpayface,只需要在程序退出时调用;

2.0 人脸识别的交互流程

2.1 人脸识别功能介绍

人脸识别通过识别用户人脸,获取用户信息(openid)。

此功能常用于商户会员、商品推荐等场景, 此流程无法用于支付。

此功能分FACEID-ONCE和FACEID-LOOP两种模式 FACEID-ONCE为直接启动人脸识别流程。 FACEID-LOOP为呼起人脸识别悬浮窗,进入等待状态,当摄像头检测到人脸时,启动人脸识别流程。

2.2 人脸识别时序图(FACEID-ONCE)

sequenceDiagram participant A as 商户APP participant B as 微信人脸sdk participant D as 商户server participant C as 微信支付后台API A ->> B: 1. 程序启动时初始化 initWxpayface B -->> A: 返回初始化结果 A ->> B: 2. 获取数据 getWxpayfaceRawdata B -->> A: 返回rawdata A ->> D: 3. 获取人脸SDK调用凭证 D ->> C: get_wxpayface_authinfo(rawdata) C -->> D: 返回authinfo D -->> A: 返回authinfo A ->> B: 4. 获取用户信息 getWxpayfaceUserInfo(authinfo) activate B B ->> B: 调用摄像头, 启动人脸识别 B ->> B: 完成人脸检测/识别 B -->> A: 返回人脸识别结果(openid) Note over A, C: 执行商户侧的逻辑 A ->> B: 5. 停止识别 stopWxpayface B ->> B: 停止识别 B -->> A: 返回 deactivate B A ->> A: 程序退出(...) A ->> B: 6. 释放资源 releaseWxpayface

2.3 人脸识别时序图(FACEID-LOOP)

sequenceDiagram participant A as 商户APP participant B as 微信人脸sdk participant D as 商户server participant C as 微信支付后台API A ->> B: 1. 程序启动时初始化 initWxpayface B -->> A: 返回初始化结果 A ->> B: 2. 获取数据 getWxpayfaceRawdata B -->> A: 返回rawdata A ->> D: 3. 获取人脸SDK调用凭证 D ->> C: get_wxpayface_authinfo(rawdata) C -->> D: 返回authinfo D -->> A: 返回authinfo A ->> B: 4. 获取用户信息 getWxpayfaceUserInfo(authinfo) activate B B ->> B: 调用摄像头, 启动悬浮窗, 进入等待状态 B ->> B: 检测到人脸, 启动人脸识别 B ->> B: 完成人脸检测/识别 B -->> A: 返回人脸识别结果(openid) Note over A, C: 执行商户侧的逻辑 A ->> B: 5. 停止识别 stopWxpayface B ->> B: 停止识别 B -->> A: 返回 deactivate B A ->> A: 程序退出(...) A ->> B: 6. 释放资源 releaseWxpayface

2.4 人脸识别后支付仅输手机号后四位时序图

此功能用于商户人脸识别获取用户信息(openid)后,再进行人脸支付可仅输入手机号后四位

sequenceDiagram participant A as 商户APP participant B as 微信人脸sdk participant D as 商户server A ->> D: 请求用户手机号(openid) D -->> A: 返回用户手机号 A ->> B: 进行人脸识别 getWxpayfaceCode(authinfo),传入用户手机号 Note over A, D: 进行人脸凭证获取,参见 2.1 人脸凭证的交互流程 B -->> A: 返回人脸识别结果(face_code, openid) Note over A, D: 进行人脸支付,参见 2.2 人脸支付时序图

2.5 人脸识别授权时序图

此功能用于商户人脸识别获取用户信息时,用户首次使用,未授权商户使用该用户人脸信息时,可进入授权页面进入授权,此流程由人脸支付APP控制,商户无需调用。

sequenceDiagram participant A as 商户APP participant B as 微信人脸sdk participant D as 商户server participant C as 微信支付后台API A ->> B: 1. 程序启动时初始化 initWxpayface B -->> A: 返回初始化结果 A ->> B: 2. 获取数据 getWxpayfaceRawdata B -->> A: 返回rawdata A ->> D: 3. 获取人脸SDK调用凭证 D ->> C: get_wxpayface_authinfo(rawdata) C -->> D: 返回authinfo D -->> A: 返回authinfo A ->> B: 4. 获取用户信息 getWxpayfaceUserInfo(authinfo) activate B B ->> B: 用户首次使用,未授权 B ->> B: 进入授权页,输入微信绑定手机号 B ->> C: get_user_info, 授权用户 C -->> B: 返回授权结果, 关闭UI B -->> A: 返回人脸识别结果(用户信息) deactivate B A ->> B: 重新启动人脸识别流程 Note over A, C: 进行人脸识别,参见 2.3 人脸识别时序图

3.0 人脸支付的交互流程

3.1 人脸支付功能介绍

获取 face_code 后,

如果前序接口face_code_type字段传值为0, 调用 旧版刷脸支付接口 完成支付

如果前序接口face_code_type字段传值为1, 调用 付款码支付接口 完成支付

3.2 人脸支付时序图

sequenceDiagram participant A as 商户APP participant D as 商户server participant C as 微信支付后台API A ->> A: 获取face_code. 参见上一节『获取人脸凭证』 A ->> D: 1. 发起订单人脸支付 D ->> C: 发起订单支付facepay(face_code, orderinfo) C -->> D: 返回支付结果 alt 支付成功/失败 D -->> A: 返回支付结果 else 支付结果未明(比如:支付中/网络超时) note over D, C: 查询支付结果 loop 直到:返回确定的订单状态(成功/失败/订单不存在)/超过轮询时间 D ->> C: 2. 查询订单状态queryorder C -->> D: 返回订单状态 end D -->> A: 返回支付结果 opt 轮询结束仍然没有支付成功 note over A, C: 撤销交易,以避免用户扣款,而没有发货的情况(撤销可后台异步进行) loop 撤销交易直到成功 D ->> C: 3. 撤销交易reverseorder C -->> D: 返回撤销结果 end end end

4.0 扫码功能的交互流程

4.1 扫码功能介绍

对于使用微信人脸sdk的支付设备,我们提供对外接口,可以在启动摄像头进行扫码,当微信人脸sdk扫码成功后,会通知扫码结果给商户APP,扫码成功间隔3000ms。

4.2 扫码功能介绍时序图

sequenceDiagram participant A as 商户APP participant B as 微信人脸sdk A ->> B: 1. 程序启动时初始化 initWxpayface B ->> A: 返回初始化结果 A ->> B: 2. 启动扫码 startCodeScanner activate B B ->> B: 打开摄像头 B ->> B: 进入扫码模式,进行扫码检测 B ->> B: 扫码成功 B ->> A: 返回返回扫码结果(code_msg) B ->> B: 3000ms后继续进入扫码模式,进行扫码检测 Note over A, B: 执行商户侧的逻辑 A ->> B: 3. 停止扫码识别 stopCodeScanner deactivate B A ->> A: 程序退出(...) A ->> B: 4. 释放资源 releaseWxpayface

5.0 实名认证的交互流程

5.1 流程功能介绍

该流程首先通过识别用户人脸、手机号,向商户返回face_sid , 商户根据 face_sid 进行用户是否已认证的判断;对于未认证的用户,可根据 face_sid 向微信后台请求进行实名认证。对于已认证的用户,可直接调用接口关闭实名认证。

该能力目前仅针对医院行业开放申请。

5.2 名词解释

face_sid:用户身份信息查询凭证,可用于用户身份查询、实名认证信息请求。

5.3 实名认证时序图

sequenceDiagram participant A as 商户APP participant B as 微信人脸SDk participant C as 微信支付后台API A ->> B: 程序启动时初始化 initWxpayface B -->> A: doInitWxpayface(返回初始化结果) A ->> B: 获取数据 getWxpayfaceRawdata B -->> A: doGetWxpayfaceRawdata(返回rawdata) A ->> B: 人脸识别 getWxpayfaceCode(face_authtype为'FACE_AUTH',face_code_type不传或者传'-1') B -->> A: 人脸识别结果(用户身份信息查询凭证:face_sid) A ->> A: 判断是否已认证 alt 需要实名认证 A->>B: 请求用户授权认证 getWxpayAuth B->>C: 请求用户认证信息 C-->>B: 用户掩码信息 alt 用户授权 B->>C: 用户已确认授权 C-->>B: 返回结果 B-->>A: 返回授权结果(SUCCESS) A->>C:请求实名认证信息 C-->>A: 返回实名认证信息 else 用户没有授权 B-->> A:返回未授权结果 end else 不需要实名认证 A->>B: 退出 getWxpayAuth(参数quit_face_auth传1字符串) end

三、各接口文档

使用方式:

  1. 安装人脸App。
  2. 商户接入人脸SDK。

注意点:

  1. 商户使用SDK接口均封装在WxPayFace类中,该类以单例形式存在。调用结果统一由`IWxPayfaceCall
  2. back`回调。
  3. 参数或回调结果以Map形式传递,方便扩展,具体字段名称及返回值定义中。

初始化(initWxpayface)

**接口作用:**对人脸SDK进行初始化

**支持版本:**1.0及以上

接口函数

//IWxPayfaceCallback
//继承自AIDL接口,方便服务商使用。目前仅提一个统一的回调接口。
public abstract interface IWxPayfaceCallback
{
  public abstract void response(Map info) throws RemoteException;
}


//WxPayFace.getInstance().initWxpayface(context,IWxPayfaceCallback);
public void initWxpayface(Context ctx, final Map info, IWxPayfaceCallback callback);

请求参数

下方参数用于WxPayFace.getInstance().initWxpayface(context,IWxPayfaceCallback); public void initWxpayface(Context ctx, final Map info, IWxPayfaceCallback callback)接口中的info信息,作用是配置人脸支付SDK的网络代理。若不需要,则调用上述接口定义中的第一个接口完成初始化操作。

另外, 针对低性能机器,我们提供了 perform_mode 参数,启用后将默认关闭美颜功能提升刷脸识别速度。

参数 必填 类型 说明
ip string HTTP代理IP或域名
port string HTTP代理端口, 须为数字
user string HTTP代理的用户名
passwd string HTTP代理的密码
proxy_type int 0:none;1:HttpTunel;2:Socks5;3:Httpv2.12及以上
tcp_port string TCP的代理端口,如果TCP代理与IP代理同一端口,则无需设置v2.12及以上
perform_mode string NORMAL_PRFORM : 正常性能表现;
LOW_PERFORM : 低性能表现
默认为正常性能表现 v2.13及以上

使用方式详见下方的实践指引:

返回参数

参数 必填 类型 说明
return_code string 错误码。公共定义见 公共错误码
return_msg string(128) 对错误码的描述

实践指引

不设置网络代理

    private void initPayFace() {
        Map<String, String> m1 = new HashMap<>();
        WxPayFace.getInstance().initWxpayface(this, m1, new IWxPayfaceCallback() {
            @Override
            public void response(Map info) throws RemoteException {
                if (info == null) {
                    new RuntimeException("调用返回为空").printStackTrace();
                    return ;
                }
                String code = (String) info.get("return_code");
                String msg = (String) info.get("return_msg");
                Log.d(TAG, "response info :: " + code + " | " + msg);
                if (code == null || !code.equals("SUCCESS")) {
                    new RuntimeException("调用返回非成功信息: " + msg).printStackTrace();
                    return ;
                }
                Log.d(TAG, "调用返回成功");
                /*
                 在这里处理您自己的业务逻辑
                 */
            }
        });
    }

设置网络代理

    private void initPayFace() {
        Map<String, String> m1 = new HashMap<>();
        m1.put("ip", "xxx.xxx.xxx.xxx"); //若没有代理,则不需要此行,代理ip请自行寻找
        m1.put("port", "8888");//若没有代理,则不需要此行,代理端口不一定是8888,根据代理设置来决定
        WxPayFace.getInstance().initWxpayface(this, m1, new IWxPayfaceCallback() {
            @Override
            public void response(Map info) throws RemoteException {
                if (info == null) {
                    new RuntimeException("调用返回为空").printStackTrace();
                    return ;
                }
                String code = (String) info.get("return_code");
                String msg = (String) info.get("return_msg");
                Log.d(TAG, "response info :: " + code + " | " + msg);
                if (code == null || !code.equals("SUCCESS")) {
                    new RuntimeException("调用返回非成功信息: " + msg).printStackTrace();
                    return ;
                }
                Log.d(TAG, "调用返回成功");
                /*
                 在这里处理您自己的业务逻辑
                 */
            }
        });
    }

设置低性能模式

    private void initPayFace() {
        Map<String, String> m1 = new HashMap<>();
        m1.put("perform_mode", "LOW_PERFORM"); //低性能表现,默认关闭美颜等
        WxPayFace.getInstance().initWxpayface(this, m1, new IWxPayfaceCallback() {
            @Override
            public void response(Map info) throws RemoteException {
                if (info == null) {
                    new RuntimeException("调用返回为空").printStackTrace();
                    return ;
                }
                String code = (String) info.get("return_code");
                String msg = (String) info.get("return_msg");
                Log.d(TAG, "response info :: " + code + " | " + msg);
                if (code == null || !code.equals("SUCCESS")) {
                    new RuntimeException("调用返回非成功信息: " + msg).printStackTrace();
                    return ;
                }
                Log.d(TAG, "调用返回成功");
                /*
                 在这里处理您自己的业务逻辑
                 */
            }
        });
    }

建议: ​ 1、您可以自定义一个Application,然后在自定义Application的onCreate()中调用initPayFace()完成人脸识别模块的初始化 ​ 2、您可以只在被调用人脸识别模块的activity的onCreate()中完成initPayFace()的调用

注意: ​ 目前我们没有在initPayFace()中做app保活的自启措施,所以当您的应用在启动过程中遇到重启/更新的问题,您必须重新调用initPayFace(),相信我们会在下一个最新的版本中对initPayFace()做进一步的完善。

获取数据 (getWxpayfaceRawdata)

**支持版本:**1.0及以上

接口函数

/*
    1.获取人脸验证信息。
        作用:获取到验证信息后,才可调用获取人识别。
        参数:
            callback:回调返回人脸验证信息。
*/
//WxPayFace.getInstance().getWxpayfaceRawdata(IWxPayfaceCallback);
public void getWxpayfaceRawdata(final IWxPayfaceCallback callback);

返回参数

参数 必填 类型 说明
return_code string 错误码。公共定义见 公共错误码
err_code Integer 可为空,二级错误码,公共定义见 二级错误码
return_msg string(128) 对错误码的描述
rawdata string(2048) 初始化数据。用于接口调用, 参见: get_wxpayface_authinfo: rawdata

实践指引

    private void getWxpayfaceRawdata() {
        WxPayFace.getInstance().getWxpayfaceRawdata(new IWxPayfaceCallback() {
            @Override
            public void response(Map info) throws RemoteException {
                if (info == null) {
                    new RuntimeException("调用返回为空").printStackTrace();
                    return;
                }
                String code = (String) info.get("return_code");
                String msg = (String) info.get("return_msg");
                Integer errcode = (Integer) info.get("err_code");
                String rawdata = info.get("rawdata").toString();
                if (code == null || rawdata == null || !code.equals("SUCCESS")) {
                    new RuntimeException("调用返回非成功信息,return_msg:" + msg + "   ").printStackTrace();
                    return ;
                }
                /*
                在这里处理您自己的业务逻辑
                 */
            }
        });
    }

获取调用凭证(get_wxpayface_authinfo)

注意,这是一个后端调用接口

**注:**返回的接口凭证authinfo,可以在expires_in指定的有效期内,同一台机具上重复使用。

接口地址

https://payapp.weixin.qq.com/face/get_wxpayface_authinfo

接口最大耗时(W): 5秒。 见下方接口耗时定义

考虑到与后台人脸支付API的一致性, 这里统一采用xml格式。

接口请求参数

参数 必填 类型 说明
store_id string(32) 门店编号, 由商户定义, 各门店唯一。
store_name string(128) 门店名称,由商户定义。(可用于展示)
device_id string(32) 终端设备编号,由商户定义。
attach string 附加字段。字段格式使用Json
rawdata string(2048) 初始化数据。由微信人脸SDK的接口返回。
获取方式参见:
[获取数据 getWxpayfaceRawdata](#获取数据 getWxpayfaceRawdata)
[获取数据 getWxpayfaceRawdata](#获取数据 getWxpayfaceRawdata)
appid string(32) 商户号绑定的公众号/小程序 appid
mch_id string(32) 商户号
sub_appid string(32) 子商户绑定的公众号/小程序 appid(服务商模式)
sub_mch_id string(32) 子商户号(服务商模式)
now int 取当前时间,10位unix时间戳。 例如:1239878956
version string 版本号。固定为1
sign_type string 签名类型,目前支持HMAC-SHA256和MD5,默认为MD5
nonce_str string(32) 随机字符串,不长于32位
sign string 参数签名。详见微信支付签名算法

示例:

<xml>
    <appid>wx31fdaErqR31</appid>
    <mch_id>12345689</mch_id>
    <now>1239878956</now>
    <version>1</version>
    <sign_type>MD5</sign_type>
    <nonce_str>V37ZHZVf2OrwsUV7kXTjTguP74c0byvE</nonce_str>
    <sign>O4TCVPAJDIK933NUSUUSS6MLIQT2PCXW</sign>
    <store_id>IMG001</store_id>
    <store_name>爱马哥南山店</store_name>
    <device_id>DEV001</device_id>
    <rawdata>H0kvnUgGHKuqflNwtNqCdOVpbO4Fd4u2NRS2uJz5/n080cOlYF5nNnuyVc+UsX0+q3nVrEYAhJFyxeG8MBx/cmZSicjI8UipaehhfFiIHnBZndrCSeGizNs6PSowudTG</rawdata>
</xml>

接口响应结果

参数 必填 类型 说明
return_code string(16) 错误码。定义见下方
return_msg string(128) 对错误码的描述
authinfo string(4096) SDK调用凭证。用于调用SDK的人脸识别接口。
参见[人脸识别 getWxpayfaceCode](#人脸识别 getWxpayfaceCode)
expires_in int authinfo的有效时间, 单位秒。 例如: 3600
在有效时间内, 对于同一台终端设备,相同的参数的前提下(如:相同的公众号、商户号、 门店编号等),可以用同一个authinfo,多次调用SDK的getWxpayfaceCode接口。
nonce_str string(32) 随机字符串
sign string 响应结果签名
appid string(32 公众号
mch_id string(32 商户号
sub_appid string(32 子商户公众账号ID(服务商模式)
sub_mch_id string(32 子商户号(服务商模式)

示例:

<return_code>SUCCESS</return_code>
<return_msg>请求成功</return_msg>
<nonce_str>Tivppi4UXAbgLxk8e1Sij76YdowOFFii</nonce_str>
<sign>PL0EUID6A7ICWNKHCSMQC0UIXOYNSE5B</sign>
<appid>wx31fdaErqR31</appid>
<mch_id>12345689</mch_id>
<authinfo>q3OPhFtQBf6KZGqmZhejKCRy5K/ch0kwS11YSsEj9XmUGqcsT2QPHt0Oa7xaCMCoSZTWMmShCo4dOiO5tU+OJEsvSxXzn5m3Nkh747tinNlbpJmVq1zOPj+FJNndkzanxoiAddO8p1EfrmUhJs/aNf0pDfrPoVfkAapK+ZY6blwyaDQ9bB7+KkZq29kObsXOZ3thg+bxP4RAqC0oxNS4JiyP0uA1Euzxtkc9lCTebloFied8stILrMehUKukeMGkZ1SzTyc8/HFHApzHahNPX6yD8ttzYnhe+IRMFJgpuTlIvEOYZUxenPXE1A5clrPvOBeJDszX/OvZl4fpYWPpXAcVQlw+gfYhblt+rT6ALMsD73w/rT4NRriQEEraC4Pfb5yua4qAqv4TVo04</authinfo>
<expires_in>7200</expires_in>

接口耗时

常见请求耗时分解见下图:

sequenceDiagram participant A as 商户server participant B as 微信支付API A ->> B: 请求网络耗时(N1) B ->> B: 接口最大耗时(W) B -->> A: 返回网络耗时(N2)

从商户server来看,接口超时应满足:

接口超时 > (N1 + N2) + W

请求/返回网络耗时(N1 + N2):

由于网络耗时主要受以下因素影响:

  • 网络环境(网络延迟/丢包率);
  • 建立https协议的网络通信;
  • 传输的数据长度;
  • 域名DNS解析

合理的网络耗时部分,由开发根据实际情况来调整。

若网络延迟< 50ms (比如ping api.mch.weixin.qq.com的延低于50ms),丢包率低的情况下,可以评估网络耗时约为2秒。

接口最大耗时(W):

由微信提供该接口需要的最长耗时。

获取用户信息(getWxpayfaceUserInfo)

**作用:**通过人脸识别获取用户信息。

**支持版本:**1.13及以上

该接口与[人脸识别 getWxpayfaceCode](#人脸识别 getWxpayfaceCode)的区别:

  1. 不需要输入手机号;
  2. 无法用于订单支付;
  3. UI交互不同。

适用范围:

适用于会员、推荐等场景。

接口函数

//WxPayFace.getInstance().getWxpayfaceUserInfo(map,IWxPayfaceCallback);
public void getWxpayfaceUserInfo(final Map info, final IWxPayfaceCallback wxpayfaceCallBack)

接口参数

参数 必填 类型 说明
appid string 商户号绑定的公众号/小程序 appid
mch_id string 商户号
sub_appid string(32) 子商户绑定的公众号/小程序 appid(可不填)
sub_mch_id string(32) 子商户号(非服务商模式不填)
store_id string 门店编号
face_authtype string 人脸识别模式。可选值:
FACEID-ONCE: 人脸识别(单次模式)
FACEID-LOOP: 人脸识别(循环模式)
authinfo string 调用凭证。获取方式参见: get_wxpayface_authinfo
ask_unionid string 是否请求获取union_id。可选值[0:不获取;1:获取]2.12新增
screen_index string 指定刷脸界面的运行屏幕,可选值:“0”运行在默认屏幕;"1"运行在第二屏幕(副屏)。系统要求: Android 8.1或以上,SDK要求:版本2.13或以上

face_authtype取值介绍

FACEID-ONCE/FACEID-LOOP:

用于获取用户信息(openid, 昵称等),通常只需要用户人脸,不需要输入手机号。

ONCE与LOOP的区别:

  • ONCE只会识别一次。 即调用本接口后, 如果在指定时间内(比如5秒)没有识别出来,则会返回识别失败。
  • LOOP会持续识别人脸, 直到识别成功为止。(或者调用停止接口)

接口返回

参数 是否一定返回 类型 说明
return_code string 错误码。公共定义见 公共错误码
err_code Integer 可为空,二级错误码,公共定义见 二级错误码
return_msg string(128) 对错误码的描述
openid S string openid
sub_openid string 子商户号下的openid(服务商模式)
nickname S string 微信昵称
token string 用于获取union_id,获取union_id文档2.12新增
unionid_code string 获取union_id 返回码。公共定义见公共错误码2.12新增
unionid_msg string 获取union_id 返回信息,对unionid_code返回码的描述2.12新增

接口返回码

错误码的公共部分, 参见公共错误码。以下为该接口独有错误码:

错误码 描述 解决方案
USER_CANCEL 用户退出人脸识别

实践指引

    public void doFaceRecognize() {
        // 详细的参数配置表可见上方的“接口参数表”
        Map<String, String> m1 = new HashMap<String, String>();
        m1.put("appid", "填您的公众号"); // 公众号,必填
        m1.put("mch_id", "填您的商户号"); // 商户号,必填
//        m1.put("sub_appid", "xxxxxxxxxxxxxx"); // 子商户公众账号ID(非服务商模式不填)
//        m1.put("sub_mch_id", "填您的子商户号"); // 子商户号(非服务商模式不填)
        m1.put("store_id", "填您的门店编号"); // 门店编号,必填
        m1.put("face_authtype", "FACEID-ONCE"); // 人脸识别模式, FACEID-ONCE`: 人脸识别(单次模式) FACEID-LOOP`: 人脸识别(循环模式), 必填
        m1.put("authinfo", "填您的调用凭证"); // 调用凭证,详见上方的接口参数
//        m1.put("ask_unionid", "1"); // 是否获取union_id    0:获取    1:不获取
        WxPayFace.getInstance().getWxpayfaceUserInfo(m1, new IWxPayfaceCallback() {
            @Override
            public void response(Map info) throws RemoteException {
                if (info == null) {
                    new RuntimeException("调用返回为空").printStackTrace();
                    return;
                }
                String code = (String) info.get("return_code"); // 错误码
                Integer errcode = (Integer) info.get("err_code"); // 二级错误码
                String msg = (String) info.get("return_msg"); // 错误码描述
                String openid = info.get("openid").toString(); // openid
                String sub_openid = ""; 
                if (info.get("sub_openid") != null) sub_openid = info.get("sub_openid").toString(); // 子商户号下的openid(服务商模式)
                String nickName = info.get("nickname").toString(); // 微信昵称
                String token = ""; 
                if (info.get("token") != null) token = info.get("token").toString(); // facesid,用户获取unionid
                if (code == null || openid == null || nickName == null || !code.equals("SUCCESS")) {
                    new RuntimeException("调用返回非成功信息,return_msg:" + msg + "   ").printStackTrace();
                    return ;
                }
                /*
                获取union_id逻辑,传入参数ask_unionid为"1"时使用
                String unionid_code = "";
                if (info.get("unionid_code") != null) unionid_code = info.get("unionid_code").toString();
                if (TextUtils.equals(unionid_code,"SUCCESS")) {
                    //获取union_id逻辑
                } else {
                    String unionid_msg = "";
                    if (info.get("unionid_msg") != null) unionid_msg = info.get("unionid_msg").toString();
                    //处理返回信息
                }
                */
                /*
                在这里处理您自己的业务逻辑
                需要注意的是:
                    1、上述注释中的内容并非是一定会返回的,它们是否返回取决于相应的条件
                    2、当您确保要解开上述注释的时候,请您做好空指针的判断,不建议直接调用
                 */
            }
        });
    }

人脸支付凭证(getWxpayfaceCode)

**作用:**启动人脸APP主界面入口,开启人脸识别,获取支付凭证或用户信息。

**支持版本:**1.0及以上

接口函数

//WxPayFace.getInstance().getWxpayfaceCode(map,IWxPayfaceCallback);
public void getWxpayfaceCode(final Map info, final IWxPayfaceCallback wxpayfaceCallBack)

接口参数

参数 必填 类型 说明
appid string 商户号绑定的公众号/小程序 appid
mch_id string 商户号
sub_appid string(32) 子商户绑定的公众号/小程序 appid(可不填)
sub_mch_id string(32) 子商户号(非服务商模式不填)
store_id string 门店编号
telephone string 用户手机号。用于传递会员手机,此手机将作为默认值, 填写到手机输入栏。即将在2.13中废弃
openid string 通过getWxpayfaceUserInfo获取的openid,传入后可使用快捷支付模式。如果也传入了telephone,将判断手机号。
out_trade_no string 商户订单号,须与调用支付接口时字段一致,该字段在在face_code_type为"1"时可不填,为"0"时必填
total_fee string 订单金额(数字), 单位分. 该字段在在face_code_type为"1"时可不填,为"0"时必填
face_authtype string 可选值:
FACEPAY: 人脸凭证,常用于人脸支付
FACEPAY_DELAY: 延迟支付(提供商户号信息联系微信支付开通权限)
FACE_AUTH: 实名认证(需联系微信支付开通权限)
authinfo string 调用凭证。获取方式参见: get_wxpayface_authinfo
ask_face_permit string 支付成功页是否需要展示人脸识别授权项。
展示:1
不展示:0
人脸识别授权项:
用户授权后用于1:N识别,可返回用户信息openid,建议商户有自己会员系统时,填1。
ask_ret_page string 是否展示微信支付成功页,可选值:"0",不展示;"1",展示
face_code_type string 目标face_code类型,可选值:"0",人脸付款码:数字字母混合,通过「刷脸支付」接口完成支付;"1",刷卡付款码:18位数字,通过「付款码支付/被扫支付」接口完成支付。如果不填写则默认为"0"
ignore_update_pay_result string 商户端是否对SDK返回支付结果,可选值:"0",返回支付结果,商户需在确认⽀付结果后调⽤[updateWxpayfacePayResult]通知SDK;"1",不返回支付结果。如果不填写则默认为"0"。
screen_index string 指定刷脸界面的运行屏幕,可选值:“0”运行在默认屏幕;"1"运行在第二屏幕(副屏)。系统要求: Android 8.1或以上,SDK要求:版本2.13或以上

face_authtype取值介绍

  • FACEPAY:

    用于获取人脸凭证(face_code),通常需要用户输入手机号以及人脸,目前主要用于人脸支付

  • FACEPAY_DELAY: 用于获取人脸凭证(face_code),应用在延迟支付场景,获取face_code后,会立即关闭微信刷脸支付app界面,用于先享后付场景,需提供商户号信息联系微信支付单独开通权限。

  • FACE_AUTH:

    用于获取用户身份信息查询凭证(face_sid),应用在实名认证场景,获取face_sid后, 通过getWxpayAuth接口获取用户实名认证授权,授权通过后可根据此face_sid向微信支付后台请求用户实名信息(具体查看微信人脸支付后台开发说明文档)。实名认证场景face_code_type不传或者传'-1'。

face_code_type取值介绍

接口返回

返回结果IWxPayfaceCallback.response(Map info)

参数 是否必然返回 类型 说明
return_code string 错误码。公共定义见 公共错误码
err_code Integer 可为空,二级错误码,公共定义见 二级错误码
return_msg string(128) 对错误码的描述
face_code S string 人脸凭证, 用于刷脸支付。
openid S string openid(相当于用户身份)
sub_openid string 子商户号下的openid(服务商模式)
telephone_used int 获取的face_code,是否使用了请求参数中的telephone
可取值:
0:表示没有使用telephone
1: 表示使用了telephone
即将在2.13中废弃
underage_state int 用户年年龄信息,使用需要联系微信支付开通权限
可取值:
0:状态不明确,或权限未开通;
1: 成年年人;
2: 未成年人

face_code 需要调用后端支付接口完成支付

微信人脸应用在返回face_code后,仍会处于等待UI(等待支付loading状态),商户应用获取到face_code后,需要调用后台人脸支付API发起支付,支付完成后调用updateWxpayfacePayResult将支付结果通知给人脸应用,人脸应用此时会关闭等待UI。

接口错误码

错误码的公共部分, 参见公共错误码。以下为该接口独有错误码:

错误码 描述 解决方案
USER_CANCEL 用户退出了人脸识别 返回到结账流程
SCAN_PAYMENT 用户选择扫码支付 进入扫码支付流程

实践指引

    public boolean doGetFaceCode() {
        Map<String, String> m1 = new HashMap<String, String>();
        m1.put("appid", "填您的微信公众号"); // 公众号,必填
        m1.put("mch_id", "填您的商户号"); // 商户号,必填
//        m1.put("sub_appid", "xxxxxxxxxxx"); // 子商户公众账号ID(非服务商模式不填)
//        m1.put("sub_mch_id", "xxxxxxxxxxx"); // 子商户号(非服务商模式不填)
        m1.put("store_id", "填您的门店编号"); // 门店编号,必填
//        m1.put("telephone", "用户手机号"); // 用户手机号,用于传递会员手机号到界面输入栏,非必填
//        m1.put("openid", "用户openid"); // 用户openid,用于快捷支付模式,非必填
        m1.put("out_trade_no", "填您的商户订单号"); // 商户订单号, 必填
        m1.put("total_fee", "填订单的金额"); // 订单金额(数字),单位:分,必填
        m1.put("face_authtype", "FACEPAY"); // FACEPAY:人脸凭证,常用于人脸支付    FACEPAY_DELAY:延迟支付   必填
        m1.put("ask_face_permit", "0"); // 展开人脸识别授权项,详情见上方接口参数,必填
//        m1.put("ask_ret_page", "0"); // 是否展示微信支付成功页,可选值:"0",不展示;"1",展示,非必填
        WxPayFace.getInstance().getWxpayfaceCode(m1, new IWxPayfaceCallback() {
            @Override
            public void response(final Map info) throws RemoteException {
                if (info == null) {
                    new RuntimeException("调用返回为空").printStackTrace();
                    return;
                }
                String code = (String) info.get("return_code"); // 错误码
                Integer errcode = (Integer) info.get("err_code"); // 二级错误码
                String msg = (String) info.get("return_msg"); // 错误码描述
                String faceCode = info.get("face_code").toString(); // 人脸凭证,用于刷脸支付
                String openid = info.get("openid").toString(); // openid
                String sub_openid = ""; // 子商户号下的openid(服务商模式)
                int telephone_used = 0; // 获取的`face_code`,是否使用了请求参数中的`telephone`
                int underage_state = 0; // 用户年龄信息(需联系微信支付开通权限)
                if (info.get("sub_openid") != null) sub_openid = info.get("sub_openid").toString();
                if (info.get("telephone_used") != null) telephone_used = Integer.parseInt(info.get("telephone_used").toString());
                if (info.get("underage_state") != null) underage_state = Integer.parseInt(info.get("underage_state").toString());
                if (code == null || faceCode == null || openid == null || !code.equals("SUCCESS")) {
                    new RuntimeException("调用返回非成功信息,return_msg:" + msg + "   ").printStackTrace();
                    return ;
                }
                /*
                在这里处理您自己的业务逻辑
                解释:您在上述中已经获得了支付凭证或者用户的信息,您可以使用这些信息通过调用支付接口来完成支付的业务逻辑
                需要注意的是:
                    1、上述注释中的内容并非是一定会返回的,它们是否返回取决于相应的条件
                    2、当您确保要解开上述注释的时候,请您做好空指针的判断,不建议直接调用
                 */
            }
        });
        return true;
    }

人脸支付后端接口

参考 后端支付接口

更新支付结果(updateWxpayfacePayResult)

作用: 商户侧确认支付结果后通知人脸SDK 更新支付结果,用户确认支付结果后返回wxpayfaceCallBack,刷脸支付界面关闭。

**支持版本:**1.0及以上

注意: 从1.14.296开始,回调时机改为刷脸支付界面关闭后触发回调。

接口函数

public void updateWxpayfacePayResult(final Map info, final IWxPayfaceCallback wxpayfaceCallBack)

接口参数

参数 必填 类型 说明
appid string 商户绑定的公众号/小程序 appid
mch_id string 商户号
store_id string 门店编号
authinfo string 调用凭证。获取方式参见: get_wxpayface_authinfo
payresult string 支付结果。可取值:
SUCCESS: 支付成功
ERROR: 支付失败

接口返回

参数 必填 类型 说明
return_code string 错误码。公共定义见 公共错误码
err_code Integer 可为空,二级错误码,公共定义见 二级错误码
return_msg string(128) 对错误码的描述

接口错误码

错误码的公共部分,参见公共错误码, 以下为该接口独有错误码:

错误码 描述 解决方案
USER_QUERY_CANCEL 用户取消查单 提示用户请与收银员确认支付结果

实践指引

  private void updateWxpayfacePayResult() {
        HashMap<String, String> map = new HashMap<String, String>();
        map.put("appid", "填您的公众号"); // 公众号,必填
        map.put("mch_id", "填您的商户号"); // 商户号,必填
        map.put("store_id", "填您的门店编号"); // 门店编号,必填
        map.put("authinfo", "填您的调用凭证"); // 调用凭证,必填
        map.put("payresult", "SUCCESS"); // 支付结果,SUCCESS:支付成功   ERROR:支付失败   必填
        WxPayFace.getInstance().updateWxpayfacePayResult(map, new IWxPayfaceCallback() {
            @Override
            public void response(Map info) throws RemoteException {
                if (info == null) {
                    new RuntimeException("调用返回为空").printStackTrace();
                    return;
                }
                String code = (String) info.get("return_code"); // 错误码
                 Integer errcode = (Integer) info.get("err_code"); // 二级错误码
                String msg = (String) info.get("return_msg"); // 错误码描述
                if (code == null || !code.equals("SUCCESS")) {
                    new RuntimeException("调用返回非成功信息,return_msg:" + msg + "   ").printStackTrace();
                    return ;
                }
                /*
                在这里处理您自己的业务逻辑:
                执行到这里说明用户已经确认支付结果且成功了,此时刷脸支付界面关闭,您可以在这里选择跳转到其它界面
                 */
            }
        });
    }

停止识别(stopWxpayface)

作用: 用于停止[获取用户信息 getWxpayfaceUserInfo](#获取用户信息 getWxpayfaceUserInfo)发起的人脸识别,以及隐藏所有的人脸标识展示。

**支持版本:**1.13及以上

接口函数

//WxPayFace.getInstance().stopWxpayface(map,IWxPayfaceCallback);
public void stopWxpayface(final Map info, final IWxPayfaceCallback wxpayfaceCallBack)

接口参数

参数 必填 类型 说明
authinfo string 调用凭证。获取方式参见: get_wxpayface_authinfo

接口返回

参数 必填 类型 说明
return_code string 错误码。公共定义见 公共错误码
err_code Integer 可为空,二级错误码,公共定义见 二级错误码
return_msg string(128) 对错误码的描述

实践指引

    private void stopFaceRecognize() {
        HashMap<String, String> map = new HashMap<String, String>();
        map.put("authinfo", "填您的调用凭证"); // 调用凭证,必填
        WxPayFace.getInstance().stopWxpayface(map, new IWxPayfaceCallback() {
            @Override
            public void response(Map info) throws RemoteException {
                if (info == null) {
                    new RuntimeException("调用返回为空").printStackTrace();
                    return;
                }
                String code = (String) info.get("return_code"); // 错误码
                 Integer errcode = (Integer) info.get("err_code"); // 二级错误码
                String msg = (String) info.get("return_msg"); // 错误码描述
                if (code == null || !code.equals("SUCCESS")) {
                    new RuntimeException("调用返回非成功信息,return_msg:" + msg + "   ").printStackTrace();
                    return ;
                }
                /*
                在这里处理您自己的业务逻辑
                 */
            }
        });
    }

统计上报(reportInfo)

接口作用: 实现点击上报,计数上报,耗时上报。

**支持版本:**1.8及以上

接口定义

//统计上报
public void reportInfo(final Map info, IWxPayfaceCallback callback);

请求参数

参数 必填 类型 说明
item string 上报项,具体说明参考表格:https://docs.qq.com/sheet/BqI21X2yZIht1zL3H34n0aOt15QzTT37rhZ60zQ7Ll0elhv72aP4hv0R4yig3rgYAK4t8pUT1W18nQ3jTeFF4
item_value long 上报项的值,必须为大于0的整数。
**点击上报:**item_value为点击次数,一般为1;
计数上报: item_value为计数值;
耗时上报: item_value为耗时值(单位毫秒)

返回参数

参数 必填 类型 说明
return_code string 错误码。公共定义见 公共错误码
err_code Integer 可为空,二级错误码,公共定义见 二级错误码
return_msg string(128) 对错误码的描述

实践指引

    // 点击上报
    public void clickReport() {
        Map<String, Object> m1 = new HashMap<String, Object>();
        // 参数设定详见上方的请求参数列表
        m1.put("item", "face.mch.module.something.count");
        m1.put("item_value", 1);  // 1 代表1次点击结果
        WxPayFace.getInstance().reportInfo(m1, new IWxPayfaceCallback() {
            @Override
            public void response(Map info) throws RemoteException {
                if (info == null) {
                    new RuntimeException("调用返回为空").printStackTrace();
                    return ;
                }
                String code = (String) info.get("return_code");
                Integer errcode = (Integer) info.get("err_code");
                String msg = (String) info.get("return_msg");
                Log.d(TAG, "response info :: " + code + " | " + msg);
                if (code == null || !code.equals("SUCCESS")) {
                    new RuntimeException("调用返回非成功信息: " + msg).printStackTrace();
                    return ;
                }
                Log.d(TAG, "调用返回成功");
                /*
                 在这里处理您自己的业务逻辑
                 */
            }
        });
    }

    // 计数上报
    public void countReport() {
        Map<String, Object> m1 = new HashMap<String, Object>();
        m1.put("item", "face.mch.module.paylist.count");
        m1.put("item_value", 23);  // value:23 数量23件 
        WxPayFace.getInstance().reportInfo(m1, new IWxPayfaceCallback() {
            @Override
            public void response(Map info) throws RemoteException {
                if (info == null) {
                    new RuntimeException("调用返回为空").printStackTrace();
                    return ;
                }
                String code = (String) info.get("return_code");
                Integer errcode = (Integer) info.get("err_code");
                String msg = (String) info.get("return_msg");
                Log.d(TAG, "response info :: " + code + " | " + msg);
                if (code == null || !code.equals("SUCCESS")) {
                    new RuntimeException("调用返回非成功信息: " + msg).printStackTrace();
                    return ;
                }
                Log.d(TAG, "调用返回成功");
                /*
                 在这里处理您自己的业务逻辑
                 */
            }
        });
    }

    // 耗时上报
    public void timeConsumingReport() {
        Map<String, Object> m1 = new HashMap<String, Object>();
        m1.put("item", "face.mch.module.paytime.costtime");
        m1.put("item_value", 2000); // value:2000 耗时2秒
        WxPayFace.getInstance().reportInfo(m1, new IWxPayfaceCallback() {
            @Override
            public void response(Map info) throws RemoteException {
                if (info == null) {
                    new RuntimeException("调用返回为空").printStackTrace();
                    return ;
                }
                String code = (String) info.get("return_code");
                Integer errcode = (Integer) info.get("err_code");
                String msg = (String) info.get("return_msg");
                Log.d(TAG, "response info :: " + code + " | " + msg);
                if (code == null || !code.equals("SUCCESS")) {
                    new RuntimeException("调用返回非成功信息: " + msg).printStackTrace();
                    return ;
                }
                Log.d(TAG, "调用返回成功");
                /*
                 在这里处理您自己的业务逻辑
                 */
            }
        });
    }

交易上报(reportOrder)

接口作用: 设备产生的非刷脸支付交易,都必须调用此接口上报交易信息, 建议每笔非刷脸支付交易发生后,都调用该接口。

支持版本: 1.12及以上

接口函数

//交易订单上报。
public void reportOrder(final Map info, final IWxPayfaceCallback callback);

请求参数

参数 必填 类型 说明
mch_id string 商户号。(若是服务商模式, 则填服务商商户号)
sub_mch_id string 子商户号。(服务商模式填写, 其它不填)
out_trade_no string 商户订单号。

返回参数

参数 必填 类型 说明
return_code string 错误码。公共定义见 公共错误码
err_code Integer 可为空,二级错误码,公共定义见 二级错误码
return_msg string(128) 对错误码的描述

实践指引

    public void reportOrder() {
        Map<String, Object> m1 = new HashMap<String, Object>();
        m1.put("mch_id", "填您的商户号"); // 商户号
//        m1.put("sub_mch_id", "填您的子商户号"); // 子商户号(非服务商模式不填)
        m1.put("out_trade_no", "填您的商户订单号");  // 填写商户订单号
        WxPayFace.getInstance().reportOrder(m1, new IWxPayfaceCallback() {
            @Override
            public void response(Map info) throws RemoteException {
                if (info == null) {
                    new RuntimeException("调用返回为空").printStackTrace();
                    return ;
                }
                String code = (String) info.get("return_code");
                Integer errcode = (Integer) info.get("err_code");
                String msg = (String) info.get("return_msg");
                Log.d(TAG, "response info :: " + code + " | " + msg);
                if (code == null || !code.equals("SUCCESS")) {
                    new RuntimeException("调用返回非成功信息: " + msg).printStackTrace();
                    return ;
                }
                Log.d(TAG, "调用返回成功");
                /*
                 在这里处理您自己的业务逻辑
                 */
            }
        });
    }

建议:上述上报模块的调用只是一个简单的示例,在实际使用的过程中,您可以构建一个单独的IWxPayfaceCallback的实例,然后在您的代码中复用它

付款码上报 reportPaycode

**接口作用:**设备获取到微信付款码,而无法获取到商户号和订单号的可以通过此接口做交易上报 **支持版本:**2.11及以上

//付款码上报
public void reportPaycode(final Map info, final IWxPayfaceCallback callback);

请求参数

参数 必填 类型 说明
auth_code string 微信支付18位付款码

接口返回

参数 必填 类型 说明
return_code string 错误码。公共定义见 公共错误码
err_code Integer 可为空,二级错误码,公共定义见 二级错误码
return_msg string(128) 对错误码的描述

实践指引

//上报付款码
Map<String, String> m1 = new HashMap<String, String>();
m1.put("auth_code", "填您的微信支付18位付款码");
WxPayFace.getInstance().reportPaycode(m1, new WxpayfaceCallback(){
            @Override
            public void response(Map info) throws RemoteException {
                if (info == null) {
                    new RuntimeException("调用返回为空").printStackTrace();
                    return ;
                }
                String code = (String) info.get("return_code");
                Integer errcode = (Integer) info.get("err_code");
                String msg = (String) info.get("return_msg");
                Log.d(TAG, "response info :: " + code + " | " + msg);
                if (code == null || !code.equals("SUCCESS")) {
                    new RuntimeException("调用返回非成功信息: " + msg).printStackTrace();
                    return ;
                }
                Log.d(TAG, "调用返回成功");
                /*
                 在这里处理您自己的业务逻辑
                 */
            }
});

建议:上述上报模块的调用只是一个简单的示例,在实际使用的过程中,您可以构建一个单独的IWxPayfaceCallback的实例,然后在您的代码中复用它

运营位控制接口(updateWxpayfaceBannerState)

作用: 设置微信支付运营图片状态,默认展示运营位浮窗,可修改为(可展示/不可展示/展示浮窗)三种状态

使用规则:联系微信支付运营同学下发

支持版本: 1.24及以上

接口函数

//WxPayFace.getInstance().updateWxpayfaceBannerState(map,IWxPayfaceCallback);
public void updateWxpayfaceBannerState(final Map bean, final IWxPayFaceCallbackAIDL wxpayfaceCallBack)

接口参数

参数 必填 类型 说明
banner_state int 设置运营位状态:
0:展示大运营图片
1:关闭所有运营图片
2:展示运营位浮窗

接口返回

参数 必填 类型 说明
return_code string 错误码。公共定义见 公共错误码
err_code Integer 可为空,二级错误码,公共定义见 二级错误码
return_msg string(128) 对错误码的描述

实践指引

    private void updateWxpayfaceBannerState() {
        HashMap<String, Integer> map = new HashMap<String, Integer>();
        map.put("banner_state", 0); // 设置运营位状态   0: 可展示运营图片   1: 不可展示运营图片 必填
        WxPayFace.getInstance().updateWxpayfaceBannerState(map, new IWxPayfaceCallback() {
            @Override
            public void response(Map info) throws RemoteException {
                if (info == null) {
                    new RuntimeException("调用返回为空").printStackTrace();
                    return;
                }
                String code = (String) info.get("return_code"); // 错误码
                Integer errcode = (Integer) info.get("err_code");//二级错误码
                String msg = (String) info.get("return_msg"); // 错误码描述
                if (code == null || !code.equals("SUCCESS")) {
                    new RuntimeException("调用返回非成功信息,return_msg:" + msg + "   ").printStackTrace();
                    return ;
                }
                /*
                在这里处理您自己的业务逻辑:
                执行到这里说明用户已经确认支付结果且成功了,此时刷脸支付界面关闭,您可以在这里选择跳转到其它界面
                 */
            }
        });
    }

启动扫码(startCodeScanner)

作用: 微信人脸sdk启动摄像头进入扫码模式

支持版本: 2.0及以上

备注:

  1. 该方法注册的回调接口在stopCodeScanner之前,扫码成功都会回调。
  2. 该方法可以多次调用,但是扫码结果只会回调最后一次注册的回调.
  3. 扫码模式和刷脸互斥,一旦开始刷脸则SDK会退出扫码模式,扫码回调失效,如果需要扫码功能,需要刷脸结束后再次调用该方法启动扫码。

接口函数

public void startCodeScanner(final IWxPayFaceCallbackAIDL cb);

接口参数

参数 必填 类型 说明
cb IWxPayFaceCallbackAIDL 扫码结果回调,该回掉为异步调用

返回参数

参数 必填 类型 说明
return_code string 错误码。公共定义见 公共错误码
err_code Integer 可为空,二级错误码,公共定义见 二级错误码
return_msg string 对错误码的描述
code_msg string 当扫码成功时返回扫码内容

实践指引

WxPayFace.getInstance().startCodeScanner(new IWxPayfaceCallback() {
    @Override
    public void response(Map info) throws RemoteException {
        if (info != null){
            String return_code = (String) info.get("return_code");
             Integer errcode = (Integer) info.get("err_code");
            String return_msg = (String) info.get("return_msg");
            String code_msg = (String) info.get("code_msg");
            final String resultString = "startCodeScanner, return_code : " + return_code + " return_msg : " + return_msg + " code_msg: " + code_msg;
            /**
            这里添加业务自定义的工作即可 注意该回调在异步线程
            **/
        }
    }
});

停止扫码(stopCodeScanner)

作用: 微信人脸sdk停止摄像头扫码,退出扫码模式

支持版本: 2.0及以上

接口函数

public void stopCodeScanner();

实践指引

WxPayFace.getInstance().stopCodeScanner();

实名认证授权(getWxpayAuth)

作用: 获得用户授权商户获取实名认证信息 **支持版本:**2.0及以上

接口函数

//WxPayFace.getInstance().getWxpayAuth(map, iWxPayfaceCallback();
WxPayFace.getInstance().getWxpayAuth(info, new IWxPayfaceCallback()

接口参数

参数 必填 类型 说明
authinfo string 调用凭证。获取方式参见: get_wxpayface_authinfo
face_sid string 用户身份信息查询凭证。获取方式见 [getWxpayfaceCode]
quit_face_auth string "1": 退出实名认证授权
其他值或不传 : 忽略

接口返回

参数 必填 类型 说明
return_code string 错误码。公共定义见 公共错误码
err_code Integer 可为空,二级错误码,公共定义见 二级错误码
return_msg string(128) 对错误码的描述见

获取小程序可用配置(getMpConfig)

作用: 获取当前机具可用的小程序启动按键值

支持版本: 2.13及以上

接口函数

public void getMpConfig(IWxPayFaceCallbackAIDL wxpayfaceCallBack)

接口参数

接口返回

参数 类型 说明
return_code string 错误码。公共定义见 公共错误码
err_code Integer 可为空,二级错误码,公共定义见 二级错误码
return_msg string(128) 对错误码的描述
VALID_MP_CONFIG String 有效的小程序启动按键值,以"|"进行分割,启动按键值,即商户在商户平台上,以”按键启动“方式,部署小程序时设置的按键值

启动小程序(launchMp)

作用: 通过有效的小程序启动按键值,启动对应的小程序

支持版本: 2.13及以上

接口函数

public void launchMp(Map bean, IWxPayFaceCallbackAIDL wxpayfaceCallBack)

接口参数

参数 必填 类型 说明
miniprogram_key_cmd string 有效的小程序启动键值
appid string 商户号绑定的公众号/小程序 appid
sub_appid string 子商户绑定的公众号/小程序 appid(可不填)
mch_id string 商户号
sub_mch_id string 子商户绑定的公众号/小程序 appid(可不填)
store_id string 门店编号
authinfo string 调用凭证。获取方式参见: get_wxpayface_authinfo

接口返回

参数 类型 说明
return_code string 错误码。公共定义见 公共错误码
err_code Integer 可为空,二级错误码,公共定义见 二级错误码
return_msg string(128) 对错误码的描述

释放资源(releaseWxpayface)

作用: 释放人脸服务,断开连接。

支持版本: 1.0及以上

接口函数

public void releaseWxpayface(Context cxt);

实践指引

private void releasePayFace() {
    WxPayFace.getInstance().releaseWxpayface(this);
}

上次更新: 3/31/2020, 8:46:10 PM