# 七、实名认证文档
通过用户刷脸授权同意身份验证后,向商户返回face_sid 和open id, 商户根据 face_sid 进行用户是否已认证的判断;对于未认证的用户,可根据 face_sid 向微信后台请求进行实名认证,用户授权实名信息(如姓名、身份证号、手机号等)后返回给商户,经过解密后才可获取加密信息。对于已认证的用户,可直接调用接口关闭实名认证。
该能力目前仅针对医院行业开放申请。
# 使用场景说明
在医院场景下,用户采用传统的刷身份证/医保卡等方式来建档、办理就医卡完成挂号、缴费、查询报告等繁杂的流程。
实名认证目前主要应用在医院的设备上:用户通过刷脸将自己的身份信息授权给医院办理相关业务,在全过程中无需刷卡操作,因此患者就诊体验变得更轻松和方便。
# 接入指引
- 申请对象范围
- 支持商户类型:普通商户、普通服务商子商户
- 支持场景:刷脸就医场景
- 场景合理性:公立医院
- 安全能力:
a) 拥有该主体下的跟实名数据对接的系统的等保三级证书,如无等保三级证书可由二级证书代替, 或者 ISO27001证。
b) 用户实名信息不得经过服务商控制的服务器,并提供【数据安全评估应答及承诺文件】 - 商户质量:主体无明确违规处罚记录
申请流程:
- 邮件标题:【刷脸实名权限申请】商户名称-服务商名称-日期
- 邮件正文:复制粘贴权限申请表表格内容及涉及实名接口的全部流程交互图
- 发送地址至wxpay_operation(微信支付医疗健康运营):wxpay_operation@tencent.com
- 抄送至sarahshao(邵霞):sarahshao@tencent.com;
- 邮件附件(相关模板如下):
① 微信刷脸接口权限申请表。点击下载申请表;
② 数据安全评估应答及承诺文件。点击下载文件;
③ 商户与平台签订的合作协议。点击下载协议;
④ 与申请商户名称完全一致的 信息系统安全等级保护三级证书(简称等保三级证书) 或者 ISO27001证,清晰的扫描件,示例如下:
- 邮件标题:【刷脸实名权限申请】商户名称-服务商名称-日期
# 接入过程
# 实名认证时序图
# 公共响应参数
参数 | 必填 | 类型 | 说明 |
---|---|---|---|
return_code | 是 | string | 错误码。公共定义见公共错误码 |
return_msg | 是 | string(128) | 对错误码的描述 |
err_code | 否 | Integer | 可为空,二级错误码,公共定义见 二级错误码 |
# 公共错误码
参数 | 错误码 | 类型 | 说明 |
---|---|---|---|
return_code | SUCCESS | string | 接口成功 |
return_code | ERROR | string | 接口失败 |
return_code | PARAM_ERROR | string | 参数错误 |
return_code | SYSTEMERROR | string | 接口返回错误 |
# 二级错误码
参数 | 错误码 | 类型 | 说明 |
---|---|---|---|
err_code | 271378620 | Interger | 刷脸服务未初始化,请调用初始化 |
err_code | 271378621 | Interger | 刷脸服务初始化中,等待500ms左右重新调用init |
# 接口调用流程
# 1、程序启动时初始化
# 程序启动时初始化initWxpayface
接口作用:对人脸SDK进行初始化
# 请求参数
除公共参数外,下方参数的代理设置可用于配置刷脸走商户内部代理。若不需要,则不用填写。
参数 | 必填 | 类型 | 说明 |
---|---|---|---|
ip | 否 | string | HTTP代理IP或域名 |
port | 否 | string | HTTP代理端口, 须为数字 |
user | 否 | string | HTTP代理的用户名 |
passwd | 否 | string | HTTP代理的密码 |
proxy_type | 否 | int | 0:none; 1:HttpTunnel; 2:Socks5; 3:Http v2.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) | 对错误码的描述 |
# 请求示例
/**
* 初始化
* 建议:
* 1、您可以自定义一个Application,然后在自定义Application的onCreate()中调用initPayFace()完成人脸识别模块的初始化
* 2、您可以只在被调用人脸识别模块的activity的onCreate()中完成initPayFace()的调用
* 注意:
* 目前我们没有在initPayFace()中做app保活的自启措施,所以当您的应用在启动过程中遇到重启/
* 更新的问题,您必须重新调用initPayFace(),相信我们会在下一个最新的版本中对initPayFace()做进一步的完善。
*/
Map<String, String> m1 = new HashMap<>();
// m1.put("ip", "192.168.1.1"); //若没有代理,则不需要此行
// m1.put("port", "8888");//若没有代理,则不需要此行
// m1.put("user", mEtnUser.getText().toString());//若没有代理,则不需要此行
// m1.put("passwd", mEtnPassword.getText().toString());//若没有代理,则不需要此行
// m1.put("proxy_type", 1 ); //若没有代理,则不需要此行
// m1.put("perform_mode", "LOW_PERFORM");//低性能表现,默认关闭美颜等
WxPayFace.getInstance().initWxpayface(this, m1, new IWxPayfaceCallback() {
@Override
public void response(Map info) throws RemoteException {
if (info == null) {
showToast("调用返回为空, 请查看日志");
new RuntimeException("调用返回为空").printStackTrace();
return false;
}
String code = (String) info.get("return_code");
String msg = (String) info.get("return_msg");
showToast("初始化完成");
}
});
# 2、获取数据
# 获取数据getWxpayfaceRawdata
接口作用:获取rawdata数据
# 返回参数
参数 | 必填 | 类型 | 说明 |
---|---|---|---|
return_code | 是 | string | 错误码。公共定义见 公共错误码 |
err_code | 否 | Integer | 可为空,二级错误码,公共定义见 二级错误码 |
return_msg | 是 | string(128) | 对错误码的描述 |
rawdata | 是 | string(2048) | 初始化数据。用于接口调用, 参见: get_wxpayface_authinfo: rawdata |
# 请求示例
/**
* 获取rawdata
* 注意:请在初始化(initWxpayface)成功后获取数据(getWxpayfaceRawdata)
*/
WxPayFace.getInstance().getWxpayfaceRawdata(new IWxPayfaceCallback() {
@Override
public void response(final Map info) throws RemoteException {
if (info == null) {
showToast("调用返回为空, 请查看日志");
new RuntimeException("调用返回为空").printStackTrace();
return false;
}
String code = (String) info.get("return_code");
String msg = (String) info.get("return_msg");
String rawdata = info.get("rawdata");
}
});
# 3、获取调用凭证
# 获取调用凭证get_wxpayface_authinfo(rawdata)(获取调用凭证)
接口作用:获取调用凭证
接口地址:https://payapp.weixin.qq.com/face/get_wxpayface_authinfo
注意:这是一个后端调用接口,请在获取数据(getWxpayfaceRewdata)成功后获取调用凭证get_wxpayface_authinfo(rawdata)
# 请求参数
参数 | 必填 | 类型 | 说明 |
---|---|---|---|
store_id | 是 | string(32) | 门店编号, 由商户定义, 各门店唯一。 |
store_name | 是 | string(128) | 门店名称,由商户定义。(可用于展示) |
device_id | 是 | string(32) | 终端设备编号,由商户定义。 |
attach | 否 | string | 附加字段。字段格式使用Json |
rawdata | 是 | string(2048) | 初始化数据。由微信人脸SDK的接口返回。 获取方式参见: 获取数据 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 | 参数签名。详见微信支付签名算法 |
# 返回参数
参数 | 必填 | 类型 | 说明 |
---|---|---|---|
return_code | 是 | string(16) | 错误码。公共定义见 公共错误码 |
return_msg | 是 | string(128) | 对错误码的描述 |
authinfo | 是 | string(4096) | SDK调用凭证。用于调用SDK的人脸识别接口。 参见: 人脸识别 getWxpayfaceCode |
expires_in | 否 | int | authinfo的有效时间, 单位秒。 例如: 3600 在有效时间内, 对于同一台终端设备,相同的参数的前提下(如:相同的公众号、商户号、 门店编号等),可以用同一个authinfo,多次调用SDK的 getWxpayfaceCode 接口。 |
nonce_str | 是 | string(32) | 随机字符串 |
sign | 是 | string(32) | 响应结果签名 |
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>
建议:返回的接口凭证authinfo
,可以在expires_in
指定的有效期内,同一台机具上重复使用
# 4、进行人脸识别
# 进行人脸识别getWxpayfaceCode(获取用户信息)
接口作用:启动人脸APP主界面入口,开启人脸识别,获取用户身份信息查询凭证。
# 请求参数
参数 | 必填 | 类型 | 说明 |
---|---|---|---|
appid | 是 | string | 商户号绑定的公众号/小程序 appid |
mch_id | 是 | string | 商户号 |
sub_appid | 否 | string(32) | 子商户绑定的公众号/小程序 appid(可不填) |
sub_mch_id | 否 | string(32) | 子商户号(非服务商模式不填) |
store_id | 是 | string | 门店编号 |
telephone | 否 | string | 用户手机号。用于传递会员手机,此手机将作为默认值, 填写到手机输入栏。 |
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 | FACE_AUTH : 实名认证(需联系微信支付开通权限) |
authinfo | 是 | string | 调用凭证。获取方式参见: get_wxpayface_authinfo |
screen_index | 否 | string | 指定刷脸界面的运行屏幕,可选值:“0”运行在默认屏幕;"1"运行在第二屏幕(副屏);"2"自动选择屏幕; "3"强制用presentation方式在第二屏幕(副屏)启动。系统要求: Android 7.1或以上(版本2.21或以上);Android 8.1或以上(版本2.13或以上) |
overlay_option | 否 | string | 指定刷脸presentation界面的层级,可选值:“0”不强制指定层级(默认);"1"强制在其他应用上层显示; |
# 返回参数
参数 | 必填 | 类型 | 说明 |
---|---|---|---|
return_code | 是 | string | 错误码。公共定义见 公共错误码 |
err_code | 否 | Integer | 可为空,二级错误码,公共定义见 二级错误码 |
return_msg | 是 | string(128) | 对错误码的描述 |
face_sid | 是 | string | 用户身份信息查询凭证 |
openid | 是 | string | openid(相当于用户身份) |
sub_openid | 否 | string | 子商户号下的openid(服务商模式) |
underage_state | 否 | int | 用户年年龄信息,使用需要联系微信支付开通权限 可取值: 0:状态不明确,或权限未开通; 1: 成年年人; 2: 未成年人 |
# 请求示例
/**
* 获取用户信息
* 注意:请在获取调用凭证get_wxpayface_authinfo(rawdata)成功后进行人脸识别(getWxpayfaceCode) ;请不要直接在副屏presentation里调用。
*/
HashMap params = new HashMap<>();
// params.put("appid", "");
// params.put("mch_id","");
// params.put("authinfo","");
...
WxPayFace.getInstance().getWxpayfaceCode(params, new IWxPayfaceCallback() {
@Override
public void response(final Map info) throws RemoteException {
if (info == null) {
showToast("调用返回为空, 请查看日志");
new RuntimeException("调用返回为空").printStackTrace();
return false;
}
String code = (String) info.get("return_code");
String msg = (String) info.get("return_msg");
String facecode = (String) info.get("face_code");
String openid = (String) info.get("openid");
String subOpenid = (String) info.get("sub_openid");
....
}
});
# 5、请求用户授权认证
# 请求用户授权认证getWxpayAuth(实名认证授权)
接口作用: 获得用户授权商户获取实名认证信息
注意:根据人脸识别返回的openid判断是否实名认证,若未认证,参数quit_face_auth传0字符串实现实名认证授权。
# 请求参数
参数 | 必填 | 类型 | 说明 |
---|---|---|---|
authinfo | 是 | string | 调用凭证。获取方式参见: get_wxpayface_authinfo |
face_sid | 是 | string | 用户身份信息查询凭证。获取方式见 [getWxpayfaceCode] |
quit_face_auth | 是 | string | "0" : 不退出实名认证授权,默认为"0" |
# 返回参数
参数 | 必填 | 类型 | 说明 |
---|---|---|---|
return_code | 是 | string | 错误码。公共定义见 公共错误码 |
err_code | 否 | Integer | 可为空,二级错误码,公共定义见 二级错误码 |
return_msg | 是 | string(128) | 对错误码的描述见 |
# 请求示例
/**
*请求用户授权认证
*注意:请在进行人脸识别getWxpayfaceCode(获取用户信息)成功后调用请求用户授权认证getWxpayAuth(实名认证授权)
*/
private void authLogic() {
HashMap<String, String> info = new HashMap<>();
info.put("authinfo","");
info.put("face_sid", "");
WxPayFace.getInstance().getWxpayAuth(info, new IWxPayfaceCallback() {
@Override
public void response(Map info) throws RemoteException {
android.util.Log.i(TAG, "实名认证返回");
StringBuilder sb = new StringBuilder();
if (info != null) {
sb.append("return_code=").append((String) info.get("return_code")).append(", ")
.append("return_msg=").append((String) info.get("return_msg"));
}
String finalResult = sb.toString();
android.util.Log.i(TAG, "实名认证返回:" + finalResult);
}
});
}
# 6、请求实名认证信息
接口作用:查询用户信息
接口地址:https://api.mch.weixin.qq.com/v3/facemch/users/{face_sid}
请求方式:GET
注意:
- 调用该接口获取授权的实名信息商户需要先申请权限,申请流程请参见如何接入。
- 这是一个APIv3接口。
- APIv3接口规则请参见:wechatpay-api-v3。
- 使用Postman调试APIv3接口请参见:wechatpay-postman-script
- 如果是服务商模式,计算签名时使用服务商的商户号和API证书。
- 获取到返回数据后,使用商户『API证书』解密数据,『不』使用平台证书。
- 从私钥文件加载密钥请参见如何在程序中加载私钥
- 解密数据,参考下面的代码:
public static String rsaDecryptOAEP(String ciphertext, PrivateKey privateKey)
throws BadPaddingException, IOException {
try {
Cipher cipher = Cipher.getInstance("RSA/ECB/PKCS1Padding");
cipher.init(Cipher.DECRYPT_MODE, privateKey);
byte[] data = Base64.getDecoder().decode(ciphertext);
return new String(cipher.doFinal(data), "utf-8");
} catch (NoSuchPaddingException | NoSuchAlgorithmException e) {
throw new RuntimeException("当前Java环境不支持RSA v1.5/OAEP", e);
} catch (InvalidKeyException e) {
throw new IllegalArgumentException("无效的私钥", e);
} catch (BadPaddingException | IllegalBlockSizeException e) {
throw new BadPaddingException("解密失败");
}
}
# 请求参数
参数 | 必填 | 类型 | 说明 |
---|---|---|---|
face_sid | 是 | string | ⼈脸识别成功后可获得接⼝调⽤凭证 注意face_sid是一个路径参数 |
info_type | 是 | string | 标识本次请求获取的信息类型 ASK_REAL_NAME:获取实名信息,包含姓名、身份证 ASK_UNION_ID:获取union id |
appid | 是 | string | 微信分配的公众账号ID |
sub_mchid | 否 | string | 微信⽀付分配的⼦商户号,服务商模式下必填 |
sub_appid | 否 | string | 微信分配的⼦商户公众账号ID |
sub_serial_no | 否 | string | ⼦商户证书序列号,服务商模式下请求实名信息必传 |
# 返回参数
参数 | 必填 | 类型 | 说明 | |
openid | 是 | string | 用户在商户appid 下的唯⼀标识 | |
sub_openid | 否 | string | 用户在⼦商户appid下的唯⼀标识,请求参数传入sub_appid时则返回 | |
real_name_info | encrypted_real_name | 否 | string | 加密后的姓名信息,商户⽤API证书私钥解密 info_type等于 ASK_REAL_NAME 时返回 |
credential_type | 否 | Integer | 证件类型, 1: 身份证 2: 护照 3: 军官证 4: ⼠兵证 5: 回乡证 6: 临时身份证 7: 户⼝簿8: 警官证 9: 台胞证 10: 营业执照 11: 其他证件 | |
encrypted_credential_id | 否 | string | 加密后的身份证号,商户用API证书私钥解密 info_type等于 ASK_REAL_ NAME 时返回 | |
union_id | 否 | string | info_type等于 ASK_UNION_ID 时返回 |
# 7、退出实名认证授权
# 退出getWxpayAuth(退出实名认证授权)
接口作用: 退出获得用户实名认证
注意:根据人脸识别返回的openid判断是否实名认证,若已认证,参数quit_face_auth传1字符串实现退出实名认证授权。
# 请求参数
参数 | 必填 | 类型 | 说明 |
---|---|---|---|
authinfo | 是 | string | 调用凭证。获取方式参见: get_wxpayface_authinfo |
face_sid | 是 | string | 用户身份信息查询凭证。获取方式见 [getWxpayfaceCode] |
quit_face_auth | 是 | string | "1": 退出实名认证授权 |
# 返回参数
参数 | 必填 | 类型 | 说明 |
---|---|---|---|
return_code | 是 | string | 错误码。公共定义见 公共错误码 |
err_code | 否 | Integer | 可为空,二级错误码,公共定义见 二级错误码 |
return_msg | 是 | string(128) | 对错误码的描述见 |
# 请求示例
/**
*实名认证授权
*注意:请在请求用户授权认证getWxpayAuth(实名认证授权)后调用退出getWxpayAuth(退出实名认证授权)
*/
private void authLogic() {
HashMap<String, String> info = new HashMap<>();
info.put("authinfo","");
info.put("face_sid", "");
WxPayFace.getInstance().getWxpayAuth(info, new IWxPayfaceCallback() {
@Override
public void response(Map info) throws RemoteException {
android.util.Log.i(TAG, "实名认证返回");
StringBuilder sb = new StringBuilder();
if (info != null) {
sb.append("return_code=").append((String) info.get("return_code")).append(", ")
.append("return_msg=").append((String) info.get("return_msg"));
}
String finalResult = sb.toString();
android.util.Log.i(TAG, "实名认证返回:" + finalResult);
}
});
}