# 七、實名認證文檔
通過用戶刷臉授權(quán)同意身份驗證后,向商戶返回face_sid 和open id, 商戶根據(jù) face_sid 進行用戶是否已認證的判斷;對于未認證的用戶,可根據(jù) face_sid 向微信后臺請求進行實名認證,用戶授權(quán)實名信息(如姓名、身份證號、手機號等)后返回給商戶,經(jīng)過解密后才可獲取加密信息。對于已認證的用戶,可直接調(diào)用接口關(guān)閉實名認證。
該能力目前僅針對醫(yī)院行業(yè)開放申請。
# 使用場景說明
在醫(yī)院場景下,用戶采用傳統(tǒng)的刷身份證/醫(yī)保卡等方式來建檔、辦理就醫(yī)卡完成掛號、繳費、查詢報告等繁雜的流程。
實名認證目前主要應(yīng)用在醫(yī)院的設(shè)備上:用戶通過刷臉將自己的身份信息授權(quán)給醫(yī)院辦理相關(guān)業(yè)務(wù),在全過程中無需刷卡操作,因此患者就診體驗變得更輕松和方便。
# 接入指引
- 申請對象范圍
- 支持商戶類型:普通商戶、普通服務(wù)商子商戶
- 支持場景:刷臉就醫(yī)場景
- 場景合理性:公立醫(yī)院
- 安全能力:
a) 擁有該主體下的跟實名數(shù)據(jù)對接的系統(tǒng)的等保三級證書,如無等保三級證書可由二級證書代替, 或者 ISO27001證。
b) 用戶實名信息不得經(jīng)過服務(wù)商控制的服務(wù)器,并提供【數(shù)據(jù)安全評估應(yīng)答及承諾文件】 - 商戶質(zhì)量:主體無明確違規(guī)處罰記錄
申請流程:
- 郵件標題:【刷臉實名權(quán)限申請】商戶名稱-服務(wù)商名稱-日期
- 郵件正文:復制粘貼權(quán)限申請表表格內(nèi)容及涉及實名接口的全部流程交互圖
- 發(fā)送地址至wxpay_operation(微信支付醫(yī)療健康運營):wxpay_operation@tencent.com
- 抄送至sarahshao(邵霞):sarahshao@tencent.com;
- 郵件附件(相關(guān)模板如下):
① 微信刷臉接口權(quán)限申請表。點擊下載申請表;
② 數(shù)據(jù)安全評估應(yīng)答及承諾文件。點擊下載文件;
③ 商戶與平臺簽訂的合作協(xié)議。點擊下載協(xié)議;
④ 與申請商戶名稱完全一致的 信息系統(tǒng)安全等級保護三級證書(簡稱等保三級證書) 或者 ISO27001證,清晰的掃描件,示例如下:
- 郵件標題:【刷臉實名權(quán)限申請】商戶名稱-服務(wù)商名稱-日期
# 接入過程
# 實名認證時序圖
# 公共響應(yīng)參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯誤碼。公共定義見公共錯誤碼 |
return_msg | 是 | string(128) | 對錯誤碼的描述 |
err_code | 否 | Integer | 可為空,二級錯誤碼,公共定義見 二級錯誤碼 |
# 公共錯誤碼
參數(shù) | 錯誤碼 | 類型 | 說明 |
---|---|---|---|
return_code | SUCCESS | string | 接口成功 |
return_code | ERROR | string | 接口失敗 |
return_code | PARAM_ERROR | string | 參數(shù)錯誤 |
return_code | SYSTEMERROR | string | 接口返回錯誤 |
# 二級錯誤碼
參數(shù) | 錯誤碼 | 類型 | 說明 |
---|---|---|---|
err_code | 271378620 | Interger | 刷臉服務(wù)未初始化,請調(diào)用初始化 |
err_code | 271378621 | Interger | 刷臉服務(wù)初始化中,等待500ms左右重新調(diào)用init |
# 接口調(diào)用流程
# 1、程序啟動時初始化
# 程序啟動時初始化initWxpayface
接口作用:對人臉SDK進行初始化
# 請求參數(shù)
除公共參數(shù)外,下方參數(shù)的代理設(shè)置可用于配置刷臉走商戶內(nèi)部代理。若不需要,則不用填寫。
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
ip | 否 | string | HTTP代理IP或域名 |
port | 否 | string | HTTP代理端口, 須為數(shù)字 |
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代理同一端口,則無需設(shè)置v2.12及以上 |
perform_mode | 否 | string | NORMAL_PRFORM : 正常性能表現(xiàn); LOW_PERFORM : 低性能表現(xiàn) 默認為正常性能表現(xiàn) v2.13及以上 |
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯誤碼。公共定義見 公共錯誤碼 |
return_msg | 是 | string(128) | 對錯誤碼的描述 |
# 請求示例
/**
* 初始化
* 建議:
* 1、您可以自定義一個Application,然后在自定義Application的onCreate()中調(diào)用initPayFace()完成人臉識別模塊的初始化
* 2、您可以只在被調(diào)用人臉識別模塊的activity的onCreate()中完成initPayFace()的調(diào)用
* 注意:
* 目前我們沒有在initPayFace()中做app保活的自啟措施,所以當您的應(yīng)用在啟動過程中遇到重啟/
* 更新的問題,您必須重新調(diào)用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");//低性能表現(xiàn),默認關(guān)閉美顏等
WxPayFace.getInstance().initWxpayface(this, m1, new IWxPayfaceCallback() {
@Override
public void response(Map info) throws RemoteException {
if (info == null) {
showToast("調(diào)用返回為空, 請查看日志");
new RuntimeException("調(diào)用返回為空").printStackTrace();
return false;
}
String code = (String) info.get("return_code");
String msg = (String) info.get("return_msg");
showToast("初始化完成");
}
});
# 2、獲取數(shù)據(jù)
# 獲取數(shù)據(jù)getWxpayfaceRawdata
接口作用:獲取rawdata數(shù)據(jù)
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯誤碼。公共定義見 公共錯誤碼 |
err_code | 否 | Integer | 可為空,二級錯誤碼,公共定義見 二級錯誤碼 |
return_msg | 是 | string(128) | 對錯誤碼的描述 |
rawdata | 是 | string(2048) | 初始化數(shù)據(jù)。用于接口調(diào)用, 參見: get_wxpayface_authinfo: rawdata |
# 請求示例
/**
* 獲取rawdata
* 注意:請在初始化(initWxpayface)成功后獲取數(shù)據(jù)(getWxpayfaceRawdata)
*/
WxPayFace.getInstance().getWxpayfaceRawdata(new IWxPayfaceCallback() {
@Override
public void response(final Map info) throws RemoteException {
if (info == null) {
showToast("調(diào)用返回為空, 請查看日志");
new RuntimeException("調(diào)用返回為空").printStackTrace();
return false;
}
String code = (String) info.get("return_code");
String msg = (String) info.get("return_msg");
String rawdata = info.get("rawdata");
}
});
# 3、獲取調(diào)用憑證
# 獲取調(diào)用憑證get_wxpayface_authinfo(rawdata)(獲取調(diào)用憑證)
接口作用:獲取調(diào)用憑證
接口地址:https://payapp.weixin.qq.com/face/get_wxpayface_authinfo
注意:這是一個后端調(diào)用接口,請在獲取數(shù)據(jù)(getWxpayfaceRewdata)成功后獲取調(diào)用憑證get_wxpayface_authinfo(rawdata)
# 請求參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
store_id | 是 | string(32) | 門店編號, 由商戶定義, 各門店唯一。 |
store_name | 是 | string(128) | 門店名稱,由商戶定義。(可用于展示) |
device_id | 是 | string(32) | 終端設(shè)備編號,由商戶定義。 |
attach | 否 | string | 附加字段。字段格式使用Json |
rawdata | 是 | string(2048) | 初始化數(shù)據(jù)。由微信人臉SDK的接口返回。 獲取方式參見: 獲取數(shù)據(jù) getWxpayfaceRawdata |
appid | 是 | string(32) | 商戶號綁定的公眾號/小程序 appid |
mch_id | 是 | string(32) | 商戶號 |
sub_appid | 否 | string(32) | 子商戶綁定的公眾號/小程序 appid(服務(wù)商模式) |
sub_mch_id | 否 | string(32) | 子商戶號(服務(wù)商模式) |
now | 是 | int | 取當前時間,10位unix時間戳。 例如:1239878956 |
version | 是 | string | 版本號。固定為1 |
sign_type | 是 | string | 簽名類型,目前支持HMAC-SHA256和MD5,默認為MD5 |
nonce_str | 是 | string(32) | 隨機字符串,不長于32位 |
sign | 是 | string | 參數(shù)簽名。詳見微信支付簽名算法 |
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string(16) | 錯誤碼。公共定義見 公共錯誤碼 |
return_msg | 是 | string(128) | 對錯誤碼的描述 |
authinfo | 是 | string(4096) | SDK調(diào)用憑證。用于調(diào)用SDK的人臉識別接口。 參見: 人臉識別 getWxpayfaceCode |
expires_in | 否 | int | authinfo的有效時間, 單位秒。 例如: 3600 在有效時間內(nèi), 對于同一臺終端設(shè)備,相同的參數(shù)的前提下(如:相同的公眾號、商戶號、 門店編號等),可以用同一個authinfo,多次調(diào)用SDK的 getWxpayfaceCode 接口。 |
nonce_str | 是 | string(32) | 隨機字符串 |
sign | 是 | string(32) | 響應(yīng)結(jié)果簽名 |
appid | 是 | string(32) | 公眾號 |
mch_id | 否 | string(32) | 商戶號 |
sub_appid | 否 | string(32) | 子商戶公眾賬號ID(服務(wù)商模式) |
sub_mch_id | 是 | string(32) | 子商戶號(服務(wù)商模式) |
# 請求示例
<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
指定的有效期內(nèi),同一臺機具上重復使用
# 4、進行人臉識別
# 進行人臉識別getWxpayfaceCode(獲取用戶信息)
接口作用:啟動人臉APP主界面入口,開啟人臉識別,獲取用戶身份信息查詢憑證。
# 請求參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
appid | 是 | string | 商戶號綁定的公眾號/小程序 appid |
mch_id | 是 | string | 商戶號 |
sub_appid | 否 | string(32) | 子商戶綁定的公眾號/小程序 appid(可不填) |
sub_mch_id | 否 | string(32) | 子商戶號(非服務(wù)商模式不填) |
store_id | 是 | string | 門店編號 |
telephone | 否 | string | 用戶手機號。用于傳遞會員手機,此手機將作為默認值, 填寫到手機輸入欄。 |
openid | 否 | string | 通過getWxpayfaceUserInfo獲取的openid,傳入后可使用快捷支付模式。如果也傳入了telephone,將判斷手機號。 |
out_trade_no | 是 | string | 商戶訂單號,須與調(diào)用支付接口時字段一致,該字段在在face_code_type 為"1"時可不填,為"0"時必填 |
total_fee | 是 | string | 訂單金額(數(shù)字), 單位分. 該字段在在face_code_type 為"1"時可不填,為"0"時必填 |
face_authtype | 是 | string | FACE_AUTH : 實名認證(需聯(lián)系微信支付開通權(quán)限) |
authinfo | 是 | string | 調(diào)用憑證。獲取方式參見: get_wxpayface_authinfo |
screen_index | 否 | string | 指定刷臉界面的運行屏幕,可選值:“0”運行在默認屏幕;"1"運行在第二屏幕(副屏);"2"自動選擇屏幕; "3"強制用presentation方式在第二屏幕(副屏)啟動。系統(tǒng)要求: Android 7.1或以上(版本2.21或以上);Android 8.1或以上(版本2.13或以上) |
overlay_option | 否 | string | 指定刷臉presentation界面的層級,可選值:“0”不強制指定層級(默認);"1"強制在其他應(yīng)用上層顯示; |
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯誤碼。公共定義見 公共錯誤碼 |
err_code | 否 | Integer | 可為空,二級錯誤碼,公共定義見 二級錯誤碼 |
return_msg | 是 | string(128) | 對錯誤碼的描述 |
face_sid | 是 | string | 用戶身份信息查詢憑證 |
openid | 是 | string | openid(相當于用戶身份) |
sub_openid | 否 | string | 子商戶號下的openid(服務(wù)商模式) |
underage_state | 否 | int | 用戶年年齡信息,使用需要聯(lián)系微信支付開通權(quán)限 可取值: 0:狀態(tài)不明確,或權(quán)限未開通; 1: 成年年人; 2: 未成年人 |
# 請求示例
/**
* 獲取用戶信息
* 注意:請在獲取調(diào)用憑證get_wxpayface_authinfo(rawdata)成功后進行人臉識別(getWxpayfaceCode) ;請不要直接在副屏presentation里調(diào)用。
*/
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("調(diào)用返回為空, 請查看日志");
new RuntimeException("調(diào)用返回為空").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、請求用戶授權(quán)認證
# 請求用戶授權(quán)認證getWxpayAuth(實名認證授權(quán))
接口作用: 獲得用戶授權(quán)商戶獲取實名認證信息
注意:根據(jù)人臉識別返回的openid判斷是否實名認證,若未認證,參數(shù)quit_face_auth傳0字符串實現(xiàn)實名認證授權(quán)。
# 請求參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
authinfo | 是 | string | 調(diào)用憑證。獲取方式參見: get_wxpayface_authinfo |
face_sid | 是 | string | 用戶身份信息查詢憑證。獲取方式見 [getWxpayfaceCode] |
quit_face_auth | 是 | string | "0" : 不退出實名認證授權(quán),默認為"0" |
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯誤碼。公共定義見 公共錯誤碼 |
err_code | 否 | Integer | 可為空,二級錯誤碼,公共定義見 二級錯誤碼 |
return_msg | 是 | string(128) | 對錯誤碼的描述見 |
# 請求示例
/**
*請求用戶授權(quán)認證
*注意:請在進行人臉識別getWxpayfaceCode(獲取用戶信息)成功后調(diào)用請求用戶授權(quán)認證getWxpayAuth(實名認證授權(quán))
*/
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
注意:
- 調(diào)用該接口獲取授權(quán)的實名信息商戶需要先申請權(quán)限,申請流程請參見如何接入。
- 這是一個APIv3接口。
- APIv3接口規(guī)則請參見:wechatpay-api-v3。
- 使用Postman調(diào)試APIv3接口請參見:wechatpay-postman-script
- 如果是服務(wù)商模式,計算簽名時使用服務(wù)商的商戶號和API證書。
- 獲取到返回數(shù)據(jù)后,使用商戶『API證書』解密數(shù)據(jù),『不』使用平臺證書。
- 從私鑰文件加載密鑰請參見如何在程序中加載私鑰
- 解密數(shù)據(jù),參考下面的代碼:
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環(huán)境不支持RSA v1.5/OAEP", e);
} catch (InvalidKeyException e) {
throw new IllegalArgumentException("無效的私鑰", e);
} catch (BadPaddingException | IllegalBlockSizeException e) {
throw new BadPaddingException("解密失敗");
}
}
# 請求參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
face_sid | 是 | string | ?臉識別成功后可獲得接?調(diào)?憑證 注意face_sid是一個路徑參數(shù) |
info_type | 是 | string | 標識本次請求獲取的信息類型 ASK_REAL_NAME:獲取實名信息,包含姓名、身份證 ASK_UNION_ID:獲取union id |
appid | 是 | string | 微信分配的公眾賬號ID |
sub_mchid | 否 | string | 微信?付分配的?商戶號,服務(wù)商模式下必填 |
sub_appid | 否 | string | 微信分配的?商戶公眾賬號ID |
sub_serial_no | 否 | string | ?商戶證書序列號,服務(wù)商模式下請求實名信息必傳 |
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 | |
openid | 是 | string | 用戶在商戶appid 下的唯?標識 | |
sub_openid | 否 | string | 用戶在?商戶appid下的唯?標識,請求參數(shù)傳入sub_appid時則返回 | |
real_name_info | encrypted_real_name | 否 | string | 加密后的姓名信息,商戶?API證書私鑰解密 info_type等于 ASK_REAL_NAME 時返回 |
credential_type | 否 | Integer | 證件類型, 1: 身份證 2: 護照 3: 軍官證 4: ?兵證 5: 回鄉(xiāng)證 6: 臨時身份證 7: 戶?簿8: 警官證 9: 臺胞證 10: 營業(yè)執(zhí)照 11: 其他證件 | |
encrypted_credential_id | 否 | string | 加密后的身份證號,商戶用API證書私鑰解密 info_type等于 ASK_REAL_ NAME 時返回 | |
union_id | 否 | string | info_type等于 ASK_UNION_ID 時返回 |
# 7、退出實名認證授權(quán)
# 退出getWxpayAuth(退出實名認證授權(quán))
接口作用: 退出獲得用戶實名認證
注意:根據(jù)人臉識別返回的openid判斷是否實名認證,若已認證,參數(shù)quit_face_auth傳1字符串實現(xiàn)退出實名認證授權(quán)。
# 請求參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
authinfo | 是 | string | 調(diào)用憑證。獲取方式參見: get_wxpayface_authinfo |
face_sid | 是 | string | 用戶身份信息查詢憑證。獲取方式見 [getWxpayfaceCode] |
quit_face_auth | 是 | string | "1": 退出實名認證授權(quán) |
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯誤碼。公共定義見 公共錯誤碼 |
err_code | 否 | Integer | 可為空,二級錯誤碼,公共定義見 二級錯誤碼 |
return_msg | 是 | string(128) | 對錯誤碼的描述見 |
# 請求示例
/**
*實名認證授權(quán)
*注意:請在請求用戶授權(quán)認證getWxpayAuth(實名認證授權(quán))后調(diào)用退出getWxpayAuth(退出實名認證授權(quán))
*/
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);
}
});
}