七、实名认证文档

2024-06-03 04:11| 来源: 网络整理| 查看: 265

# 七、实名认证文档

通过用户刷脸授权同意身份验证后，向商户返回face_sid 和open id，商户根据 face_sid 进行用户是否已认证的判断；对于未认证的用户，可根据 face_sid 向微信后台请求进行实名认证，用户授权实名信息（如姓名、身份证号、手机号等）后返回给商户，经过解密后才可获取加密信息。对于已认证的用户，可直接调用接口关闭实名认证。

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

# 使用场景说明

在医院场景下，用户采用传统的刷身份证/医保卡等方式来建档、办理就医卡完成挂号、缴费、查询报告等繁杂的流程。

实名认证目前主要应用在医院的设备上：用户通过刷脸将自己的身份信息授权给医院办理相关业务，在全过程中无需刷卡操作，因此患者就诊体验变得更轻松和方便。

# 接入指引申请对象范围支持商户类型：普通商户、普通服务商子商户支持场景：刷脸就医场景场景合理性：公立医院安全能力： a) 拥有该主体下的跟实名数据对接的系统的等保三级证书，如无等保三级证书可由二级证书代替，或者 ISO27001证。 b) 用户实名信息不得经过服务商控制的服务器，并提供【数据安全评估应答及承诺文件】商户质量：主体无明确违规处罚记录

申请流程：

邮件标题：【刷脸实名权限申请】商户名称-服务商名称-日期邮件正文：复制粘贴权限申请表表格内容及涉及实名接口的全部流程交互图发送地址至wxpay_operation(微信支付医疗健康运营)：[email protected] 抄送至sarahshao(邵霞)：[email protected]；邮件附件（相关模板如下）： ① 微信刷脸接口权限申请表。点击下载申请表； ② 数据安全评估应答及承诺文件。点击下载文件； ③ 商户与平台签订的合作协议。点击下载协议； ④ 与申请商户名称完全一致的信息系统安全等级保护三级证书（简称等保三级证书）或者 ISO27001证，清晰的扫描件，示例如下：

# 接入过程

# 实名认证时序图 sequenceDiagram participant A as 商户APP participant B as 微信人脸SDk participant C as 商户server participant D as 微信支付后台API Note over A, D: Step 1：程序启动时初始化 A ->> B: 1. 程序启动时初始化 initWxpayface B -->> A: doInitWxpayface(返回初始化结果) Note over A, D: Step 2：获取数据，返回人脸识别结果 A ->> B: 2. 获取数据 getWxpayfaceRawdata B -->> A: doGetWxpayfaceRawdata(返回rawdata) A ->> C: 3. 获取人脸SDK调用凭证 C ->> D: get_wxpayface_authinfo(rawdata) D -->> C: 返回authinfo C -->> A: 返回authinfo A ->> B: 4. 人脸识别 getWxpayfaceCode（authinfo） B -->> A: 人脸识别结果(用户身份信息查询凭证：face_sid、openid) A ->> A: 根据openid判断是否已认证 alt 需要实名认证 Note over A, D: Step 3：请求用户授权认证 A->>B: 5. 请求用户授权认证 getWxpayAuth(参数quit_face_auth传“0”字符串) B->>D: 请求用户认证信息 D-->>B: 用户掩码信息 alt 用户授权 B->>D: 用户已确认授权 D-->>B: 返回结果 B-->>A: 返回授权结果(SUCCESS) Note over A, D: Step 4：请求实名认证信息，完成认证 A->>C:6. 请求实名认证信息 C->>D: 请求实名认证信息 D-->>C: 返回实名认证信息 C-->>A:返回实名认证信息 else 用户没有授权 B-->> A:返回未授权结果 end else 不需要实名认证 A->>B: 7. 退出 getWxpayAuth(参数quit_face_auth传"1"字符串) end # 公共响应参数参数必填类型说明 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: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) 对错误码的描述 # 请求示例 /** * 初始化 * 建议： * 1、您可以自定义一个Application，然后在自定义Application的onCreate()中调用initPayFace()完成人脸识别模块的初始化 * 2、您可以只在被调用人脸识别模块的activity的onCreate()中完成initPayFace()的调用 * 注意： * 目前我们没有在initPayFace()中做app保活的自启措施，所以当您的应用在启动过程中遇到重启/ * 更新的问题，您必须重新调用initPayFace()，相信我们会在下一个最新的版本中对initPayFace()做进一步的完善。 */ Map 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) 子商户号(服务商模式) # 请求示例 SUCCESS 请求成功 Tivppi4UXAbgLxk8e1Sij76YdowOFFii PL0EUID6A7ICWNKHCSMQC0UIXOYNSE5B wx31fdaErqR31 12345689 q3OPhFtQBf6KZGqmZhejKCRy5K/ch0kwS11YSsEj9XmUGqcsT2QPHt0Oa7xaCMCoSZTWMmShCo4dOiO5tU+OJEsvSxXzn5m3Nkh747tinNlbpJmVq1zOPj+FJNndkzanxoiAddO8p1EfrmUhJs/aNf0pDfrPoVfkAapK+ZY6blwyaDQ9bB7+KkZq29kObsXOZ3thg+bxP4RAqC0oxNS4JiyP0uA1Euzxtkc9lCTebloFied8stILrMehUKukeMGkZ1SzTyc8/HFHApzHahNPX6yD8ttzYnhe+IRMFJgpuTlIvEOYZUxenPXE1A5clrPvOBeJDszX/OvZl4fpYWPpXAcVQlw+gfYhblt+rT6ALMsD73w/rT4NRriQEEraC4Pfb5yua4qAqv4TVo04 7200

建议：返回的接口凭证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 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 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); } }); } 上次更新: 12/9/2022, 11:08:13 AM

← 六、支付分功能文档八、其他接口对接 →

【本文地址】

公司简介

联系我们