# 一、刷臉支付文檔
# 刷臉支付場(chǎng)景說明
該流程通過識(shí)別用戶人臉、手機(jī)號(hào),獲取人臉憑證(face_code),該人臉憑證具有較高的安全等級(jí),可用于支付。
# 接入過程
接口調(diào)用注意事項(xiàng):
在刷臉支付流程中,Step1之前不進(jìn)行過多的主線程耗時(shí)操作,避免耗時(shí)累計(jì)導(dǎo)致啟動(dòng)刷臉慢影響用戶體驗(yàn)。
# 刷臉支付時(shí)序圖
# 公共響應(yīng)參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯(cuò)誤碼。公共定義見公共錯(cuò)誤碼 |
return_msg | 是 | string(128) | 對(duì)錯(cuò)誤碼的描述 |
err_code | 否 | Integer | 可為空,二級(jí)錯(cuò)誤碼,公共定義見 二級(jí)錯(cuò)誤碼 |
# 1、公共錯(cuò)誤碼
參數(shù) | 錯(cuò)誤碼 | 類型 | 說明 |
---|---|---|---|
return_code | SUCCESS | string | 接口成功 |
return_code | ERROR | string | 接口失敗 |
return_code | PARAM_ERROR | string | 參數(shù)錯(cuò)誤 |
return_code | SYSTEMERROR | string | 接口返回錯(cuò)誤 |
# 2、二級(jí)錯(cuò)誤碼
參數(shù) | 錯(cuò)誤碼 | 類型 | 說明 |
---|---|---|---|
err_code | 271378620 | Interger | 刷臉服務(wù)未初始化,請(qǐng)調(diào)用初始化 |
err_code | 271378621 | Interger | 刷臉服務(wù)初始化中,等待500ms左右重新調(diào)用init |
# 接口調(diào)用流程
# 1、程序啟動(dòng)時(shí)初始化
# 程序啟動(dòng)時(shí)初始化initWxpayface
接口作用:對(duì)人臉SDK進(jìn)行初始化
# 請(qǐng)求參數(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) 默認(rèn)為正常性能表現(xiàn) v2.13及以上 |
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯(cuò)誤碼。公共定義見 公共錯(cuò)誤碼 |
return_msg | 是 | string(128) | 對(duì)錯(cuò)誤碼的描述 |
# 請(qǐng)求示例
/**
* 初始化
*
*/
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),默認(rèn)關(guān)閉美顏等
WxPayFace.getInstance().initWxpayface(this, m1, new IWxPayfaceCallback() {
@Override
public void response(Map info) throws RemoteException {
if (info == null) {
showToast("調(diào)用返回為空, 請(qǐng)查看日志");
new RuntimeException("調(diào)用返回為空").printStackTrace();
return false;
}
String code = (String) info.get("return_code");
String msg = (String) info.get("return_msg");
showToast("初始化完成");
}
});
建議:1、您可以自定義一個(gè)Application,然后在自定義Application的onCreate()中調(diào)用initPayFace()完成人臉識(shí)別模塊的初始化 2、您可以只在被調(diào)用人臉識(shí)別模塊的activity的onCreate()中完成initPayFace()的調(diào)用
注意:目前我們沒有在initPayFace()中做app保活的自啟措施,所以當(dāng)您的應(yīng)用在啟動(dòng)過程中遇到重啟/更新的問題,您必須重新調(diào)用initPayFace(),相信我們會(huì)在下一個(gè)最新的版本中對(duì)initPayFace()做進(jìn)一步的完善。
# 2、獲取數(shù)據(jù)
# 獲取數(shù)據(jù)getWxpayfaceRawdata
接口作用:獲取rawdata數(shù)據(jù)
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯(cuò)誤碼。公共定義見 公共錯(cuò)誤碼 |
err_code | 否 | Integer | 可為空,二級(jí)錯(cuò)誤碼,公共定義見 二級(jí)錯(cuò)誤碼 |
return_msg | 是 | string(128) | 對(duì)錯(cuò)誤碼的描述 |
rawdata | 是 | string(2048) | 初始化數(shù)據(jù)。用于接口調(diào)用, 參見: get_wxpayface_authinfo: rawdata |
# 請(qǐng)求示例
/**
* 獲取rawdata
*
*/
WxPayFace.getInstance().getWxpayfaceRawdata(new IWxPayfaceCallback() {
@Override
public void response(final Map info) throws RemoteException {
if (info == null) {
showToast("調(diào)用返回為空, 請(qǐng)查看日志");
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");
}
});
注意:請(qǐng)?jiān)诔跏蓟?initWxpayface)成功后獲取數(shù)據(jù)(getWxpayfaceRawdata)
# 3、獲取調(diào)用憑證
# 獲取調(diào)用憑證get_wxpayface_authinfo(rawdata)(獲取調(diào)用憑證)
接口作用:獲取調(diào)用憑證
接口地址:https://payapp.weixin.qq.com/face/get_wxpayface_authinfo
# 請(qǐng)求參數(shù)
除公共參數(shù)外,下方參數(shù)的代理設(shè)置可用于配置刷臉走商戶內(nèi)部代理。若不需要,則不用填寫。
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
store_id | 是 | string(32) | 門店編號(hào), 由商戶定義, 各門店唯一。 |
store_name | 是 | string(128) | 門店名稱,由商戶定義。(可用于展示) |
device_id | 是 | string(32) | 終端設(shè)備編號(hào),由商戶定義。 |
attach | 否 | string | 附加字段。字段格式使用Json |
rawdata | 是 | string(2048) | 初始化數(shù)據(jù)。由微信人臉SDK的接口返回。 獲取方式參見: [獲取數(shù)據(jù) getWxpayfaceRawdata](#獲取數(shù)據(jù) getWxpayfaceRawdata) [獲取數(shù)據(jù) getWxpayfaceRawdata](#獲取數(shù)據(jù) getWxpayfaceRawdata) |
appid | 是 | string(32) | 商戶號(hào)綁定的公眾號(hào)/小程序 appid |
mch_id | 是 | string(32) | 商戶號(hào) |
sub_appid | 否 | string(32) | 子商戶綁定的公眾號(hào)/小程序 appid(服務(wù)商模式) |
sub_mch_id | 否 | string(32) | 子商戶號(hào)(服務(wù)商模式) |
now | 是 | int | 取當(dāng)前時(shí)間,10位unix時(shí)間戳。 例如:1239878956 |
version | 是 | string | 版本號(hào)。固定為1 |
sign_type | 是 | string | 簽名類型,目前支持HMAC-SHA256和MD5,默認(rèn)為MD5 |
nonce_str | 是 | string(32) | 隨機(jī)字符串,不長(zhǎng)于32位 |
sign | 是 | string | 參數(shù)簽名。詳見微信支付簽名算法 |
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string(16) | 錯(cuò)誤碼。公共定義見 公共錯(cuò)誤碼 |
return_msg | 是 | string(128) | 對(duì)錯(cuò)誤碼的描述 |
authinfo | 是 | string(4096) | SDK調(diào)用憑證。用于調(diào)用SDK的人臉識(shí)別接口。 參見[人臉識(shí)別 getWxpayfaceCode](#人臉識(shí)別 getWxpayfaceCode) |
expires_in | 否 | int | authinfo的有效時(shí)間, 單位秒。 例如: 3600 在有效時(shí)間內(nèi), 對(duì)于同一臺(tái)終端設(shè)備,相同的參數(shù)的前提下(如:相同的公眾號(hào)、商戶號(hào)、 門店編號(hào)等),可以用同一個(gè)authinfo,多次調(diào)用SDK的 getWxpayfaceCode 接口。 |
nonce_str | 是 | string(32) | 隨機(jī)字符串 |
sign | 是 | string(32) | 響應(yīng)結(jié)果簽名 |
appid | 是 | string(32) | 公眾號(hào) |
mch_id | 否 | string(32) | 商戶號(hào) |
sub_appid | 否 | string(32) | 子商戶公眾賬號(hào)ID(服務(wù)商模式) |
sub_mch_id | 是 | string(32) | 子商戶號(hào)(服務(wù)商模式) |
# 請(qǐng)求示例
<return_code>SUCCESS</return_code>
<return_msg>請(qǐng)求成功</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),同一臺(tái)機(jī)具上重復(fù)使用
注意:減少調(diào)用get_wxpayface_authinfo接口可有效減少啟動(dòng)耗時(shí),提升用戶體驗(yàn)。對(duì)于同一臺(tái)終端設(shè)備,相同的參數(shù)的前提下,get_wxpayface_authinfo接口返回的authinfo在expires_in有效時(shí)間內(nèi)可以重復(fù)使用,未過期建議使用緩存authinfo,即將過期再進(jìn)行調(diào)用續(xù)期即可。
# 4、啟動(dòng)防火墻配置(非必須)
注意:這一步不是必須的,且只支持v2.21版本以上; 僅適用配置了固定IP訪問微信刷臉的商戶使用
# 啟動(dòng)防火墻配置enableFirewall
接口作用:如果您網(wǎng)絡(luò)有防火墻,并且在后臺(tái)配置了域名和IP關(guān)系,則可以調(diào)用這個(gè)方法,調(diào)用成功之后,微信支付SDK進(jìn)行網(wǎng)絡(luò)訪問時(shí),如果遇到配置的域名,則只會(huì)訪問這個(gè)域名配置的對(duì)應(yīng)IP列表中的IP。這樣您的防火墻配置白名單IP時(shí)只需配置這些IP。該方法重啟后還會(huì)生效,除非調(diào)用disableFirewall。
# 接口參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
mchId | 是 | string | 商戶Id |
subMchId | 是 | string | 子商戶Id |
wxpayfaceCallBack | 是 | IWxPayFaceCallbackAIDL | 回調(diào) |
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯(cuò)誤碼。公共定義見 公共錯(cuò)誤碼 |
err_code | 否 | Integer | 可為空,二級(jí)錯(cuò)誤碼,公共定義見 二級(jí)錯(cuò)誤碼 |
return_msg | 是 | string(128) | 對(duì)錯(cuò)誤碼的描述 |
# 請(qǐng)求示例
/**
* 啟動(dòng)防火墻配置
* @param mchId 商戶Id
* @param subMchId 子商戶Id
* @param wxpayfaceCallBack 回調(diào)
*/
WxPayFace.getInstance().enableFirewall("商戶ID", "子商戶ID", new IWxPayfaceCallback() {
@Override
public void response(Map info) throws RemoteException {
if (!isSuccessInfo(info)) {
return;
}
showToast("初始化防火墻完成");
}
});
注意:請(qǐng)?jiān)诔跏蓟?initWxpayface)成功后再調(diào)用
# 5、進(jìn)行人臉識(shí)別
# 進(jìn)行人臉識(shí)別getWxpayfaceCode(獲取用戶信息)
接口作用:?jiǎn)?dòng)人臉APP主界面入口,開啟人臉識(shí)別,獲取支付憑證或用戶信息。第一個(gè)callback參數(shù)wxpayfaceCallBack負(fù)責(zé)獲取付款碼,第二個(gè)callback參數(shù)updateResultWxpayfaceCallBack負(fù)責(zé)監(jiān)聽SDK查單退出。
# 請(qǐng)求參數(shù)
除公共參數(shù)外,下方參數(shù)的代理設(shè)置可用于配置刷臉走商戶內(nèi)部代理。若不需要,則不用填寫。
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
appid | 是 | string | 商戶號(hào)綁定的公眾號(hào)/小程序 appid |
mch_id | 是 | string | 商戶號(hào) |
sub_appid | 否 | string(32) | 子商戶綁定的公眾號(hào)/小程序 appid(可不填) |
sub_mch_id | 否 | string(32) | 子商戶號(hào)(非服務(wù)商模式不填) |
store_id | 是 | string | 門店編號(hào) |
openid | 否 | string | 通過getWxpayfaceUserInfo獲取的openid,傳入后可使用快捷支付模式。如果也傳入了telephone,將判斷手機(jī)號(hào)。 |
out_trade_no | 是 | string | 商戶訂單號(hào),須與調(diào)用支付接口時(shí)字段一致,該字段在在face_code_type 為"1"時(shí)可不填,為"0"時(shí)必填 |
total_fee | 是 | string | 訂單金額(數(shù)字), 單位分. 該字段在在face_code_type 為"1"時(shí)可不填,為"0"時(shí)必填 |
face_authtype | 是 | string | 可選值:FACEPAY : 人臉憑證,常用于人臉支付FACEPAY_DELAY : 延遲支付(提供商戶號(hào)信息聯(lián)系微信支付開通權(quán)限) FACE_AUTH : 實(shí)名認(rèn)證(需聯(lián)系微信支付開通權(quán)限) |
authinfo | 是 | string | 調(diào)用憑證。獲取方式參見: get_wxpayface_authinfo |
ask_ret_page | 否 | string | 是否展示微信支付成功頁,可選值:"0",不展示;"1",展示。 V2.13后無效 |
face_code_type | 是 | string | 目標(biāo)face_code類型,必填值:"1",刷卡付款碼:18位數(shù)字,通過「付款碼支付/被掃支付」接口完成支付。 |
ignore_update_pay_result | 否 | string | 商戶端是否對(duì)SDK返回支付結(jié)果,可選值:"0",返回支付結(jié)果,商戶需在確認(rèn)?付結(jié)果后調(diào)?[updateWxpayfacePayResult]通知SDK;"1",不返回支付結(jié)果。如果不填寫則默認(rèn)為"0"。 V2.13后無效 |
screen_index | 否 | string | 指定刷臉界面的運(yùn)行屏幕,可選值:“0”, 運(yùn)行在主屏; "1", 運(yùn)行在副屏; "2", 雙屏同顯; "3", 強(qiáng)制用presentation方式運(yùn)行在副屏; "4", 副屏運(yùn)行刷臉,主屏展示引導(dǎo)窗 |
overlay_option | 否 | string | 指定刷臉presentation界面的層級(jí),可選值:“0”不強(qiáng)制指定層級(jí)(默認(rèn));"1"強(qiáng)制在其他應(yīng)用上層顯示; |
# 接口wxpayfaceCallBack返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯(cuò)誤碼。公共定義見 公共錯(cuò)誤碼 |
err_code | 否 | Integer | 可為空,二級(jí)錯(cuò)誤碼,公共定義見 二級(jí)錯(cuò)誤碼 |
return_msg | 是 | string(128) | 對(duì)錯(cuò)誤碼的描述 |
face_code | 是 | string | 人臉憑證, 用于刷臉支付。 |
openid | 是 | string | openid(相當(dāng)于用戶身份) |
sub_openid | 否 | string | 子商戶號(hào)下的openid(服務(wù)商模式) |
underage_state | 否 | int | 用戶年齡信息,使用需要聯(lián)系微信支付開通權(quán)限 可取值: 0:狀態(tài)不明確,或權(quán)限未開通; 1: 成年年人; 2: 未成年人 |
# 接口updateResultWxpayfaceCallBack返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯(cuò)誤碼(USER_QUERY_CANCEL和SUCCESS)。公共定義見 公共錯(cuò)誤碼 |
return_msg | 是 | string(128) | 對(duì)錯(cuò)誤碼的描述 |
# 請(qǐng)求示例1
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)用返回為空, 請(qǐng)查看日志");
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");
....
}
});
建議:請(qǐng)?jiān)讷@取調(diào)用憑證get_wxpayface_authinfo(rawdata)成功后進(jìn)行人臉識(shí)別(getWxpayfaceCode)
# 請(qǐng)求示例2
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)用返回為空, 請(qǐng)查看日志");
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");
....
}
}, new IWxPayfaceCallback() {
@Override
public void response(Map info) throws RemoteException {
if (info == null) {
new RuntimeException("調(diào)用返回為空").printStackTrace();
return;
}
String code = (String) info.get("return_code"); // 錯(cuò)誤碼
String msg = (String) info.get("return_msg"); // 錯(cuò)誤碼描述
if (code == null || !code.equals("SUCCESS")) {
new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + " ").printStackTrace();
return ;
}
/*
在這里處理您自己的業(yè)務(wù)邏輯:
執(zhí)行到這里說明用戶已經(jīng)確認(rèn)支付結(jié)果且成功了,此時(shí)刷臉支付界面關(guān)閉,您可以在這里選擇跳轉(zhuǎn)到其它界面
*/
}
});
建議:請(qǐng)?jiān)讷@取調(diào)用憑證get_wxpayface_authinfo(rawdata)成功后進(jìn)行人臉識(shí)別(getWxpayfaceCode) ; 請(qǐng)不要直接在副屏presentation里調(diào)用。
# 6、退出刷臉
# 退出刷臉頁面quitWxpayface(2.22及以上版本新增)
接口作用:在刷臉過程中,只要付款碼還沒有返回,都可以調(diào)用該接口退出刷臉,通常用于用戶不想刷臉的時(shí)候調(diào)用該接口退出刷臉
# 請(qǐng)求參數(shù)
除公共參數(shù)外,下方參數(shù)的代理設(shè)置可用于配置刷臉走商戶內(nèi)部代理。若不需要,則不用填寫。
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
map | 是 | Map<String, String> | 示例:map.put("toast_text", "退出刷臉支付"); put的key必須是string類型,value也必須是string類型,如果map填空,則默認(rèn)會(huì)彈"商家已取消刷臉"的toast提示,否則可以在map中put一個(gè)key為"toast_text"的參數(shù)來自定義toast提示文本 |
wxpayfaceCallBack | 是 | IWxPayFaceCallbackAIDL | 退出刷臉接口回調(diào),可以填空,回調(diào)回來的也是一個(gè)map,里面包含退出刷臉的return_code和return_msg |
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯(cuò)誤碼。公共定義見 公共錯(cuò)誤碼 |
return_msg | 是 | string(128) | 對(duì)錯(cuò)誤碼的描述 |
# 請(qǐng)求示例
/**
*退出刷臉
*
*/
Map map = new HashMap();
map.put("toast_text", "商家已停止刷臉");
WxPayFace.getInstance().quitWxpayface(map, new IWxPayfaceCallback() {
@Override
public void response(Map info) throws RemoteException {
// 通常不用,可以打印出來方便問題分析跟進(jìn)
String returnCode = (String) info.get("return_code");
String msg = (String) info.get("return_msg");
}
});
# 7、進(jìn)行發(fā)起訂單支付
# 進(jìn)行發(fā)起訂單支付micropay
接口作用:發(fā)起訂單支付
接口地址:https://api.mch.weixin.qq.com/pay/micropay
# 請(qǐng)求參數(shù)
注: 如果有分賬需求,請(qǐng)參考分賬文檔, 普通商戶分賬 服務(wù)商分賬
除公共參數(shù)外,下方參數(shù)的代理設(shè)置可用于配置刷臉走商戶內(nèi)部代理。若不需要,則不用填寫。
參數(shù) | 必填 | 類型 | 示例值 | 說明 |
---|---|---|---|---|
appid | 是 | String(32) | wx8888888888888888 | 微信分配的公眾賬號(hào)ID(企業(yè)號(hào)corpid即為此appId) |
mch_id | 是 | String(32) | 1900000109 | 微信支付分配的商戶號(hào) |
device_info | 否 | String(32) | 013467007045764 | 終端設(shè)備號(hào)(商戶自定義,如門店編號(hào)) |
nonce_str | 是 | String(32) | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS | 隨機(jī)字符串,不長(zhǎng)于32位。推薦隨機(jī)數(shù)生成算法 |
sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 簽名,詳見簽名生成算法 |
sign_type | 否 | String(32) | HMAC-SHA256 | 簽名類型,目前支持HMAC-SHA256和MD5,默認(rèn)為MD5 |
body | 是 | String(128) | image形象店-深圳騰大- QQ公仔 | 商品簡(jiǎn)單描述,該字段須嚴(yán)格按照規(guī)范傳遞,具體請(qǐng)見參數(shù)規(guī)定 |
detail | 否 | String(6000) | 單品優(yōu)惠功能字段,需要接入詳見單品優(yōu)惠詳細(xì)說明 | |
attach | 否 | String(127) | 說明 | 附加數(shù)據(jù),在查詢API和支付通知中原樣返回,該字段主要用于商戶攜帶訂單的自定義數(shù)據(jù) |
out_trade_no | 是 | String(32) | 1217752501201407033233368018 | 商戶系統(tǒng)內(nèi)部訂單號(hào),要求32個(gè)字符內(nèi),只能是數(shù)字、大小寫字母_-|*且在同一個(gè)商戶號(hào)下唯一。詳見商戶訂單號(hào) |
total_fee | 是 | Int | 888 | 訂單總金額,單位為分,只能為整數(shù),詳見支付金額 |
fee_type | 否 | String(16) | CNY | 符合ISO4217標(biāo)準(zhǔn)的三位字母代碼,默認(rèn)人民幣:CNY,詳見貨幣類型 |
spbill_create_ip | 是 | String(64) | 8.8.8.8 | 支持IPV4和IPV6兩種格式的IP地址。調(diào)用微信支付API的機(jī)器IP |
goods_tag | 否 | String(32) | 1234 | 訂單優(yōu)惠標(biāo)記,代金券或立減優(yōu)惠功能的參數(shù),詳見代金券或立減優(yōu)惠 |
limit_pay | 否 | String(32) | no_credit | no_credit--指定不能使用信用卡支付 |
time_start | 否 | String(14) | 20091225091010 | 訂單生成時(shí)間,格式為yyyyMMddHHmmss,如2009年12月25日9點(diǎn)10分10秒表示為20091225091010。其他詳見時(shí)間規(guī)則 |
time_expire | 否 | String(14) | 20091227091010 | 訂單失效時(shí)間,格式為yyyyMMddHHmmss,如2009年12月27日9點(diǎn)10分10秒表示為20091227091010。注意:最短失效時(shí)間間隔需大于1分鐘 |
receipt | 否 | String(8) | Y | Y,傳入Y時(shí),支付成功消息和支付詳情頁將出現(xiàn)開票入口。需要在微信支付商戶平臺(tái)或微信公眾平臺(tái)開通電子發(fā)票功能,傳此字段才可生效 |
auth_code | 是 | String(128) | 120061098828009406 | 掃碼支付付款碼,設(shè)備讀取用戶微信中的條碼或者二維碼信息 (注:用戶付款碼條形碼規(guī)則:18位純數(shù)字,以10、11、12、13、14、15開頭) |
scene_info | 否 | String(256) | {"store_info" : { "id": "SZTX001", "name": "騰大餐廳", "area_code": "440305", "address": "科技園中一路騰訊大廈" }} | 該字段用于上報(bào)場(chǎng)景信息,目前支持上報(bào)實(shí)際門店信息。該字段為JSON對(duì)象數(shù)據(jù),對(duì)象格式為{"store_info":{"id": "門店ID","name": "名稱","area_code": "編碼","address": "地址" }} ,字段詳細(xì)說明請(qǐng)點(diǎn)擊行前的+展開 |
# 請(qǐng)求示例
<xml>
<appid>wx2421b1c4370ec43b</appid>
<attach>訂單額外描述</attach>
<auth_code>120269300684844649</auth_code>
<body>付款碼支付測(cè)試</body>
<device_info>1000</device_info>
<goods_tag></goods_tag>
<mch_id>10000100</mch_id>
<nonce_str>8aaee146b1dee7cec9100add9b96cbe2</nonce_str>
<out_trade_no>1415757673</out_trade_no>
<spbill_create_ip>14.17.22.52</spbill_create_ip>
<time_expire></time_expire>
<total_fee>1</total_fee>
<sign>C29DB7DB1FD4136B84AE35604756362C</sign>
</xml>
注:參數(shù)值用XML轉(zhuǎn)義即可,CDATA標(biāo)簽用于說明數(shù)據(jù)不被XML解析器解析。
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 示例值 | 說明 |
---|---|---|---|---|
return_code | 是 | String(16) | SUCCESS | SUCCESS/FAIL此字段是接口通信情況標(biāo)識(shí),非交易成功與否的標(biāo)識(shí) |
return_msg | 是 | String(128) | OK | 當(dāng)return_code為FAIL時(shí)返回信息為錯(cuò)誤原因 ,例如簽名失敗參數(shù)格式校驗(yàn)錯(cuò)誤 |
當(dāng)return_code為SUCCESS的時(shí)候,還會(huì)包括以下字段:
參數(shù) | 必填 | 類型 | 示例值 | 說明 |
---|---|---|---|---|
appid | 是 | String(32) | wx8888888888888888 | 調(diào)用接口提交的公眾賬號(hào)ID |
mch_id | 是 | String(32) | 1900000109 | 調(diào)用接口提交的商戶號(hào) |
device_info | 否 | String(32) | 013467007045764 | 調(diào)用接口提交的終端設(shè)備號(hào), |
nonce_str | 是 | String(32) | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS | 微信返回的隨機(jī)字符串 |
sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 微信返回的簽名,詳見簽名生成算法 |
result_code | 是 | String(16) | SUCCESS | SUCCESS/FAIL |
err_code | 否 | String(32) | SYSTEMERROR | 詳細(xì)參見錯(cuò)誤列表 |
err_code_des | 否 | String(128) | 系統(tǒng)錯(cuò)誤 | 錯(cuò)誤返回的信息描述 |
當(dāng)return_code 和result_code都為SUCCESS的時(shí),還會(huì)包括以下字段:
參數(shù) | 必填 | 類型 | 示例值 | 說明 |
---|---|---|---|---|
openid | 是 | String(128) | Y | 用戶在商戶appid 下的唯一標(biāo)識(shí) |
is_subscribe | 是 | String(1) | Y | 用戶是否關(guān)注公眾賬號(hào),僅在公眾賬號(hào)類型支付有效,取值范圍:Y或N;Y-關(guān)注;N-未關(guān)注 |
trade_type | 是 | String(16) | MICROPAY | MICROPAY 付款碼支付 |
bank_type | 是 | String(32) | CMC | 銀行類型,采用字符串類型的銀行標(biāo)識(shí),詳見銀行類型 |
fee_type | 否 | String(16) | CNY | 符合ISO 4217標(biāo)準(zhǔn)的三位字母代碼,默認(rèn)人民幣:CNY,詳見貨幣類型 |
total_fee | 是 | Int | 888 | 訂單總金額,單位為分,只能為整數(shù),詳見支付金額 |
settlement_total_fee | 否 | Int | 100 | 當(dāng)訂單使用了免充值型優(yōu)惠券后返回該參數(shù),應(yīng)結(jié)訂單金額=訂單金額-免充值優(yōu)惠券金額。 |
coupon_fee | 否 | Int | 100 | “代金券”金額<=訂單金額,訂單金額-“代金券”金額=現(xiàn)金支付金額,詳見支付金額 |
cash_fee_type | 否 | String(16) | CNY | 符合ISO 4217標(biāo)準(zhǔn)的三位字母代碼,默認(rèn)人民幣:CNY,其他值列表詳見貨幣類型 |
cash_fee | 是 | Int | 100 | 訂單現(xiàn)金支付金額,詳見支付金額 |
transaction_id | 是 | String(32) | 1217752501201407033233368018 | 微信支付訂單號(hào) |
out_trade_no | 是 | String(32) | 1217752501201407033233368018 | 商戶系統(tǒng)內(nèi)部訂單號(hào),要求32個(gè)字符內(nèi),只能是數(shù)字、大小寫字母_-|*且在同一個(gè)商戶號(hào)下唯一。 |
attach | 否 | String(128) | 123456 | 商家數(shù)據(jù)包,原樣返回 |
time_end | 是 | String(14) | 20141030133525 | 訂單生成時(shí)間,格式為yyyyMMddHHmmss,如2009年12月25日9點(diǎn)10分10秒表示為20091225091010。詳見時(shí)間規(guī)則 |
promotion_detail | 否 | String(6000) | 示例見下文 | 新增返回,單品優(yōu)惠功能字段,需要接入請(qǐng)見詳細(xì)說明 |
# 請(qǐng)求示例
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
<appid><![CDATA[wx2421b1c4370ec43b]]></appid>
<mch_id><![CDATA[10000100]]></mch_id>
<device_info><![CDATA[1000]]></device_info>
<nonce_str><![CDATA[GOp3TRyMXzbMlkun]]></nonce_str>
<sign><![CDATA[D6C76CB785F07992CDE05494BB7DF7FD]]></sign>
<result_code><![CDATA[SUCCESS]]></result_code>
<openid><![CDATA[oUpF8uN95-Ptaags6E_roPHg7AG0]]></openid>
<is_subscribe><![CDATA[Y]]></is_subscribe>
<trade_type><![CDATA[MICROPAY]]></trade_type>
<bank_type><![CDATA[CCB_DEBIT]]></bank_type>
<total_fee>1</total_fee>
<coupon_fee>0</coupon_fee>
<fee_type><![CDATA[CNY]]></fee_type>
<transaction_id><![CDATA[1008450740201411110005820873]]></transaction_id>
<out_trade_no><![CDATA[1415757673]]></out_trade_no>
<attach><![CDATA[訂單額外描述]]></attach>
<time_end><![CDATA[20141111170043]]></time_end>
</xml>
# 錯(cuò)誤碼
名稱 | 描述 | 支付狀態(tài) | 原因 | 解決方案 |
---|---|---|---|---|
SYSTEMERROR | 接口返回錯(cuò)誤 | 支付結(jié)果未知 | 系統(tǒng)超時(shí) | 請(qǐng)立即調(diào)用被掃訂單結(jié)果查詢API,查詢當(dāng)前訂單狀態(tài),并根據(jù)訂單的狀態(tài)決定下一步的操作。 |
PARAM_ERROR | 參數(shù)錯(cuò)誤 | 支付確認(rèn)失敗 | 請(qǐng)求參數(shù)未按指引進(jìn)行填寫 | 請(qǐng)根據(jù)接口返回的詳細(xì)信息檢查您的程序 |
ORDERPAID | 訂單已支付 | 支付確認(rèn)失敗 | 訂單號(hào)重復(fù) | 請(qǐng)確認(rèn)該訂單號(hào)是否重復(fù)支付,如果是新單,請(qǐng)使用新訂單號(hào)提交 |
NOAUTH | 商戶無權(quán)限 | 支付確認(rèn)失敗 | 商戶沒有開通被掃支付權(quán)限 | 請(qǐng)開通商戶號(hào)權(quán)限。請(qǐng)聯(lián)系產(chǎn)品或商務(wù)申請(qǐng) |
AUTHCODEEXPIRE | 二維碼已過期,請(qǐng)用戶在微信上刷新后再試 | 支付確認(rèn)失敗 | 用戶的條碼已經(jīng)過期 | 請(qǐng)收銀員提示用戶,請(qǐng)用戶在微信上刷新條碼,然后請(qǐng)收銀員重新掃碼。 直接將錯(cuò)誤展示給收銀員 |
NOTENOUGH | 余額不足 | 支付確認(rèn)失敗 | 用戶的零錢余額不足 | 請(qǐng)收銀員提示用戶更換當(dāng)前支付的卡,然后請(qǐng)收銀員重新掃碼。建議:商戶系統(tǒng)返回給收銀臺(tái)的提示為“用戶余額不足.提示用戶換卡支付” |
NOTSUPORTCARD | 不支持卡類型 | 支付確認(rèn)失敗 | 用戶使用卡種不支持當(dāng)前支付形式 | 請(qǐng)用戶重新選擇卡種 建議:商戶系統(tǒng)返回給收銀臺(tái)的提示為“該卡不支持當(dāng)前支付,提示用戶換卡支付或綁新卡支付” |
ORDERCLOSED | 訂單已關(guān)閉 | 支付確認(rèn)失敗 | 該訂單已關(guān) | 商戶訂單號(hào)異常,請(qǐng)重新下單支付 |
ORDERREVERSED | 訂單已撤銷 | 支付確認(rèn)失敗 | 當(dāng)前訂單已經(jīng)被撤銷 | 當(dāng)前訂單狀態(tài)為“訂單已撤銷”,請(qǐng)?zhí)崾居脩糁匦轮Ц?/td> |
BANKERROR | 銀行系統(tǒng)異常 | 支付結(jié)果未知 | 銀行端超時(shí) | 請(qǐng)立即調(diào)用被掃訂單結(jié)果查詢API,查詢當(dāng)前訂單的不同狀態(tài),決定下一步的操作。 |
USERPAYING | 用戶支付中,需要輸入密碼 | 支付結(jié)果未知 | 該筆交易因?yàn)闃I(yè)務(wù)規(guī)則要求,需要用戶輸入支付密碼。 | 等待5秒,然后調(diào)用被掃訂單結(jié)果查詢API,查詢當(dāng)前訂單的不同狀態(tài),決定下一步的操作。 |
AUTH_CODE_ERROR | 付款碼參數(shù)錯(cuò)誤 | 支付確認(rèn)失敗 | 請(qǐng)求參數(shù)未按指引進(jìn)行填寫 | 每個(gè)二維碼僅限使用一次,請(qǐng)刷新再試 |
AUTH_CODE_INVALID | 付款碼檢驗(yàn)錯(cuò)誤 | 支付確認(rèn)失敗 | 收銀員掃描的不是微信支付的條碼 | 請(qǐng)掃描微信支付被掃條碼/二維碼 |
XML_FORMAT_ERROR | XML格式錯(cuò)誤 | 支付確認(rèn)失敗 | XML格式錯(cuò)誤 | 請(qǐng)檢查XML參數(shù)格式是否正確 |
REQUIRE_POST_METHOD | 請(qǐng)使用post方法 | 支付確認(rèn)失敗 | 未使用post傳遞參數(shù) | 請(qǐng)檢查請(qǐng)求參數(shù)是否通過post方法提交 |
SIGNERROR | 簽名錯(cuò)誤 | 支付確認(rèn)失敗 | 參數(shù)簽名結(jié)果不正確 | 請(qǐng)檢查簽名參數(shù)和方法是否都符合簽名算法要求 |
LACK_PARAMS | 缺少參數(shù) | 支付確認(rèn)失敗 | 缺少必要的請(qǐng)求參數(shù) | 請(qǐng)檢查參數(shù)是否齊全 |
NOT_UTF8 | 編碼格式錯(cuò)誤 | 支付確認(rèn)失敗 | 未使用指定編碼格式 | 請(qǐng)使用UTF-8編碼格式 |
BUYER_MISMATCH | 支付帳號(hào)錯(cuò)誤 | 支付確認(rèn)失敗 | 暫不支持同一筆訂單更換支付方 | 請(qǐng)確認(rèn)支付方是否相同 |
APPID_NOT_EXIST | APPID不存在 | 支付確認(rèn)失敗 | 參數(shù)中缺少APPID | 請(qǐng)檢查APPID是否正確 |
MCHID_NOT_EXIST | MCHID不存在 | 支付確認(rèn)失敗 | 參數(shù)中缺少M(fèi)CHID | 請(qǐng)檢查MCHID是否正確 |
OUT_TRADE_NO_USED | 商戶訂單號(hào)重復(fù) | 支付確認(rèn)失敗 | 同一筆交易不能多次提交 | 請(qǐng)核實(shí)商戶訂單號(hào)是否重復(fù)提交 |
APPID_MCHID_NOT_MATCH | appid和mch_id不匹配 | 支付確認(rèn)失敗 | appid和mch_id不匹配 | 請(qǐng)確認(rèn)appid和mch_id是否匹配 |
INVALID_REQUEST | 無效請(qǐng)求 | 支付確認(rèn)失敗 | 商戶系統(tǒng)異常導(dǎo)致,商戶權(quán)限異常、重復(fù)請(qǐng)求支付、證書錯(cuò)誤、頻率限制等 | 請(qǐng)確認(rèn)商戶系統(tǒng)是否正常,是否具有相應(yīng)支付權(quán)限,確認(rèn)證書是否正確,控制頻率 |
TRADE_ERROR | 交易錯(cuò)誤 | 支付確認(rèn)失敗 | 業(yè)務(wù)錯(cuò)誤導(dǎo)致交易失敗、用戶賬號(hào)異常、風(fēng)控、規(guī)則限制等 | 請(qǐng)確認(rèn)帳號(hào)是否存在異常 |
注意:
- ◆ 這是一個(gè)后端接口,請(qǐng)?jiān)谌四樧R(shí)別成功后發(fā)起支付
- ◆ 如果當(dāng)前交易返回的支付狀態(tài)是明確的錯(cuò)誤原因造成的支付失敗(支付確認(rèn)失敗),請(qǐng)重新下單支付;如果當(dāng)前交易返回的支付狀態(tài)是不明錯(cuò)誤(支付結(jié)果未知),請(qǐng)調(diào)用查詢訂單接口確認(rèn)狀態(tài),如果長(zhǎng)時(shí)間(建議30秒)都得不到明確狀態(tài)請(qǐng)調(diào)用撤銷訂單接口。
# 8、查詢訂單狀態(tài)
# 查詢訂單狀態(tài)orderquery
接口作用:該接口提供所有微信支付訂單的查詢,商戶可以通過查詢訂單接口主動(dòng)查詢訂單狀態(tài),完成下一步的業(yè)務(wù)邏輯。
需要調(diào)用查詢接口的情況:
- ◆ 當(dāng)商戶后臺(tái)、網(wǎng)絡(luò)、服務(wù)器等出現(xiàn)異常,商戶系統(tǒng)最終未接收到支付通知;
- ◆ 調(diào)用支付接口后,返回系統(tǒng)錯(cuò)誤或未知交易狀態(tài)情況;
- ◆ 調(diào)用付款碼支付API,返回USERPAYING的狀態(tài);
- ◆ 調(diào)用關(guān)單或撤銷接口API之前,需確認(rèn)支付狀態(tài);
接口地址:https://api.mch.weixin.qq.com/pay/orderquery
# 請(qǐng)求參數(shù)
除公共參數(shù)外,下方參數(shù)的代理設(shè)置可用于配置刷臉走商戶內(nèi)部代理。若不需要,則不用填寫。
參數(shù) | 必填 | 類型 | 說明 | 示例值 |
---|---|---|---|---|
appid | 是 | String(32) | 微信支付分配的公眾賬號(hào)ID(企業(yè)號(hào)corpid即為此appId) | wxd678efh567hg6787 |
mch_id | 是 | String(32) | 微信支付分配的商戶號(hào) | 1230000109 |
transaction_id | 否 | String(32) | 微信的訂單號(hào),建議優(yōu)先使用 | 1009660380201506130728806387 |
out_trade_no | 否 | String(32) | 商戶系統(tǒng)內(nèi)部訂單號(hào),要求32個(gè)字符內(nèi),只能是數(shù)字、大小寫字母_-|*@ ,且在同一個(gè)商戶號(hào)下唯一。 詳見商戶訂單號(hào) | 20150806125346 |
nonce_str | 是 | String(32) | 隨機(jī)字符串,不長(zhǎng)于32位。推薦隨機(jī)數(shù)生成算法 | C380BEC2BFD727A4B6845133519F3AD6 |
sign | 是 | String(32) | 通過簽名算法計(jì)算得出的簽名值,詳見簽名生成算法 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
sign_type | 否 | String(32) | 簽名類型,目前支持HMAC-SHA256和MD5,默認(rèn)為MD5 | HMAC-SHA256 |
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 | 示例值 |
---|---|---|---|---|
return_code | 是 | String(16) | SUCCESS/FAIL,此字段是通信標(biāo)識(shí),非交易標(biāo)識(shí),交易是否成功需要查看trade_state來判斷 | SUCCESS |
return_msg | 是 | String(128) | 當(dāng)return_code為FAIL時(shí)返回信息為錯(cuò)誤原因 ,例如簽名失敗參、數(shù)格式校驗(yàn)錯(cuò)誤 | OK |
以下字段在return_code為SUCCESS的時(shí)候有返回
參數(shù) | 必填 | 類型 | 說明 | 示例值 |
---|---|---|---|---|
appid | 是 | String(32) | 微信分配的公眾賬號(hào)ID | wxd678efh567hg6787 |
mch_id | 是 | String(32) | 微信支付分配的商戶號(hào) | 1230000109 |
nonce_str | 是 | String(32) | 隨機(jī)字符串,不長(zhǎng)于32位。推薦隨機(jī)數(shù)生成算法 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
sign | 是 | String(32) | 簽名,詳見簽名生成算法 | C380BEC2BFD727A4B6845133519F3AD6 |
result_code | 是 | String(16) | SUCCESS/FAIL | SUCCESS |
err_code | 否 | String(32) | 當(dāng)result_code為FAIL時(shí)返回錯(cuò)誤代碼,詳細(xì)參見下文錯(cuò)誤列表 | |
err_code_des | 否 | String(128) | 當(dāng)result_code為FAIL時(shí)返回錯(cuò)誤描述,詳細(xì)參見下文錯(cuò)誤列表 |
以下字段在return_code 、result_code、trade_state都為SUCCESS時(shí)有返回 ,如trade_state不為 SUCCESS,則只返回out_trade_no(必傳)和attach(選傳)。
參數(shù) | 必填 | 類型 | 說明 | 示例值 |
---|---|---|---|---|
device_info | 否 | String(32) | 微信支付分配的終端設(shè)備號(hào) | 013467007045764 |
openid | 是 | String(128) | 用戶在商戶appid下的唯一標(biāo)識(shí) | oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
is_subscribe | 是 | String(1) | 用戶是否關(guān)注公眾賬號(hào),Y-關(guān)注,N-未關(guān)注 | Y |
trade_type | 是 | String(16) | 調(diào)用接口提交的交易類型,取值如下:JSAPI,NATIVE,APP,MICROPAY,詳細(xì)說明見參數(shù)規(guī)定 | JSAPI |
trade_state | 是 | String(32) | SUCCESS—支付成功,REFUND—轉(zhuǎn)入退款當(dāng)result_code為FAIL時(shí)返回錯(cuò)誤代碼,詳細(xì)參見下文錯(cuò)誤列表,NOTPAY—未支付當(dāng)result_code為FAIL時(shí)返回錯(cuò)誤描述,詳細(xì)參見下文錯(cuò)誤列表,CLOSED—已關(guān)閉,REVOKED—已撤銷(付款碼支付),USERPAYING--用戶支付中(付款碼支付),PAYERROR--支付失敗(其他原因,如銀行返回失敗),支付狀態(tài)機(jī)請(qǐng)見下單API頁面 | SUCCESS |
bank_type | 是 | String(16) | 銀行類型,采用字符串類型的銀行標(biāo)識(shí) | CMC |
total_fee | 是 | int | 訂單總金額,單位為分 | 100 |
settlement_total_fee | 否 | int | 當(dāng)訂單使用了免充值型優(yōu)惠券后返回該參數(shù),應(yīng)結(jié)訂單金額=訂單金額-免充值優(yōu)惠券金額。 | 100 |
fee_type | 否 | String(8) | 貨幣類型,符合ISO 4217標(biāo)準(zhǔn)的三位字母代碼,默認(rèn)人民幣:CNY,其他值列表詳見貨幣類型 | CNY |
cash_fee | 是 | int | 現(xiàn)金支付金額訂單現(xiàn)金支付金額,詳見支付金額 | 100 |
cash_fee_type | 否 | String(16) | 貨幣類型,符合ISO 4217標(biāo)準(zhǔn)的三位字母代碼,默認(rèn)人民幣:CNY,其他值列表詳見貨幣類型 | CNY |
coupon_fee | 否 | int | “代金券”金額<=訂單金額,訂單金額-“代金券”金額=現(xiàn)金支付金額,詳見支付金額 | CNY |
coupon_count | 否 | int | 代金券使用數(shù)量 | 1 |
coupon_type_$n | 否 | String | CASH--充值代金券,NO_CASH---非充值優(yōu)惠券,開通免充值券功能,并且訂單使用了優(yōu)惠券后有返回(取值:CASH、NO_CASH)。$n為下標(biāo),從0開始編號(hào),舉例:coupon_type_$0 | CASH |
coupon_id_$n | 否 | String(20) | 代金券ID, $n為下標(biāo),從0開始編號(hào) | 10000 |
coupon_fee_$n | 否 | int | 單個(gè)代金券支付金額, $n為下標(biāo),從0開始編號(hào) | 100 |
transaction_id | 是 | String(32) | 微信支付訂單號(hào) | 1009660380201506130728806387 |
out_trade_no | 是 | String(32) | 商戶系統(tǒng)內(nèi)部訂單號(hào),要求32個(gè)字符內(nèi),只能是數(shù)字、大小寫字母_-|*@ ,且在同一個(gè)商戶號(hào)下唯一。 | 20150806125346 |
attach | 否 | String(128) | 附加數(shù)據(jù),原樣返回 | 深圳分店 |
time_end | 是 | String(14) | 訂單支付時(shí)間,格式為yyyyMMddHHmmss,如2009年12月25日9點(diǎn)10分10秒表示為20091225091010。其他詳見時(shí)間規(guī)則 | 20141030133525 |
trade_state_desc | 是 | String(256) | 對(duì)當(dāng)前查詢訂單狀態(tài)的描述和下一步操作的指引 | 支付失敗,請(qǐng)重新下單支付 |
# 請(qǐng)求示例
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
<appid><![CDATA[wx2421b1c4370ec43b]]></appid>
<mch_id><![CDATA[10000100]]></mch_id>
<device_info><![CDATA[1000]]></device_info>
<nonce_str><![CDATA[TN55wO9Pba5yENl8]]></nonce_str>
<sign><![CDATA[BDF0099C15FF7BC6B1585FBB110AB635]]></sign>
<result_code><![CDATA[SUCCESS]]></result_code>
<openid><![CDATA[oUpF8uN95-Ptaags6E_roPHg7AG0]]></openid>
<is_subscribe><![CDATA[Y]]></is_subscribe>
<trade_type><![CDATA[MICROPAY]]></trade_type>
<bank_type><![CDATA[CCB_DEBIT]]></bank_type>
<total_fee>1</total_fee>
<fee_type><![CDATA[CNY]]></fee_type>
<transaction_id><![CDATA[1008450740201411110005820873]]></transaction_id>
<out_trade_no><![CDATA[1415757673]]></out_trade_no>
<attach><![CDATA[訂單額外描述]]></attach>
<time_end><![CDATA[20141111170043]]></time_end>
<trade_state><![CDATA[SUCCESS]]></trade_state>
</xml>
# 錯(cuò)誤碼
名稱 | 描述 | 原因 | 解決方案 |
---|---|---|---|
ORDERNOTEXIST | 此交易訂單號(hào)不存在 | 查詢系統(tǒng)中不存在此交易訂單號(hào) | 該API只能查提交支付交易返回成功的訂單,請(qǐng)商戶檢查需要查詢的訂單號(hào)是否正確 |
SYSTEMERROR | 系統(tǒng)錯(cuò)誤 | 后臺(tái)系統(tǒng)返回錯(cuò)誤 | 系統(tǒng)異常,請(qǐng)?jiān)僬{(diào)用發(fā)起查詢 |
注意:這是一個(gè)后端接口
# 9、撤銷交易
# 撤銷交易reverse
接口作用:支付交易返回失敗或支付系統(tǒng)超時(shí),調(diào)用該接口撤銷交易。如果此訂單用戶支付失敗,微信支付系統(tǒng)會(huì)將此訂單關(guān)閉;如果用戶支付成功,微信支付系統(tǒng)會(huì)將此訂單資金退還給用戶。
注意:7天以內(nèi)的交易單可調(diào)用撤銷,其他正常支付的單如需實(shí)現(xiàn)相同功能請(qǐng)調(diào)用申請(qǐng)退款A(yù)PI。提交支付交易后調(diào)用【查詢訂單API】,沒有明確的支付結(jié)果再調(diào)用【撤銷訂單API】。
調(diào)用支付接口后請(qǐng)勿立即調(diào)用撤銷訂單API,建議支付后至少15s后再調(diào)用撤銷訂單接口
接口地址:https://api.mch.weixin.qq.com/secapi/pay/reverse
# 請(qǐng)求參數(shù)
除公共參數(shù)外,下方參數(shù)的代理設(shè)置可用于配置刷臉走商戶內(nèi)部代理。若不需要,則不用填寫。
字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
---|---|---|---|---|---|
公眾賬號(hào)ID | appid | 是 | String(32) | wx8888888888888888 | 微信分配的公眾賬號(hào)ID(企業(yè)號(hào)corpid即為此appId) |
商戶號(hào) | mch_id | 是 | String(32) | 1900000109 | 微信支付分配的商戶號(hào) |
微信訂單號(hào) | transaction_id | 否 | String(32) | 1217752501201407033233368018 | 微信的訂單號(hào),優(yōu)先使用 |
商戶訂單號(hào) | out_trade_no | 是 | String(32) | 1217752501201407033233368018 | 商戶系統(tǒng)內(nèi)部的訂單號(hào),transaction_id、out_trade_no二選一,如果同時(shí)存在優(yōu)先級(jí):transaction_id> out_trade_no |
隨機(jī)字符串 | nonce_str | 是 | String(32) | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS | 隨機(jī)字符串,不長(zhǎng)于32位。推薦隨機(jī)數(shù)生成算法 |
簽名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 簽名,詳見簽名生成算法 |
簽名類型 | sign_type | 否 | String(32) | HMAC-SHA256 | 簽名類型,目前支持HMAC-SHA256和MD5,默認(rèn)為MD5 |
# 返回參數(shù)
字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
---|---|---|---|---|---|
返回狀態(tài)碼 | return_code | 是 | String(16) | SUCCESS | SUCCESS/FAIL此字段是通信標(biāo)識(shí),非交易標(biāo)識(shí),交易是否成功需要查看trade_state來判斷 |
返回信息 | return_msg | 是 | String(128) | OK | 當(dāng)return_code為FAIL時(shí)返回信息為錯(cuò)誤原因 ,例如簽名失敗參數(shù)格式校驗(yàn)錯(cuò)誤 |
當(dāng)return_code為SUCCESS的時(shí)候,還會(huì)包括以下字段:
字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
---|---|---|---|---|---|
公眾賬號(hào)ID | appid | 是 | String(32) | wx8888888888888888 | 返回提交的公眾賬號(hào)ID |
商戶號(hào) | mch_id | 是 | String(32) | 1900000109 | 返回提交的商戶號(hào) |
隨機(jī)字符串 | nonce_str | 是 | String(32) | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS | 微信返回的隨機(jī)字符串 |
簽名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 返回?cái)?shù)據(jù)的簽名,詳見簽名算法 |
業(yè)務(wù)結(jié)果 | result_code | 是 | String(16) | SUCCESS | SUCCESS/FAIL |
錯(cuò)誤代碼 | err_code | 否 | String(32) | SYSTEMERROR | 詳細(xì)參見錯(cuò)誤列表 |
錯(cuò)誤描述 | err_code_des | 否 | String(128) | 系統(tǒng)錯(cuò)誤 | 結(jié)果信息描述 |
是否重調(diào) | recall | 是 | String(1) | Y | 是否需要繼續(xù)調(diào)用撤銷,Y-需要,N-不需要 |
# 請(qǐng)求示例
<xml>
<appid>wx2421b1c4370ec43b</appid>
<mch_id>10000100</mch_id>
<nonce_str>b7ffb16a7150cf08639db472c5f5bdae</nonce_str>
<out_trade_no>1415717424</out_trade_no>
<sign>9B2EA16C05A5CEF8E53B14D53932D012</sign>
</xml>
# 返回示例
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
<appid><![CDATA[wx2421b1c4370ec43b]]></appid>
<mch_id><![CDATA[10000100]]></mch_id>
<nonce_str><![CDATA[o5bAKF3o2ypC8hwa]]></nonce_str>
<sign><![CDATA[6F5080EDDD196FFCDE53F786BBB93899]]></sign>
<result_code><![CDATA[SUCCESS]]></result_code>
<recall><![CDATA[N]]></recall>
</xml>
# 錯(cuò)誤碼
名稱 | 描述 | 原因 | 解決方案 |
---|---|---|---|
SYSTEMERROR | 接口返回錯(cuò)誤 | 系統(tǒng)超時(shí) | 請(qǐng)立即調(diào)用被掃訂單結(jié)果查詢API,查詢當(dāng)前訂單狀態(tài),并根據(jù)訂單的狀態(tài)決定下一步的操作。 |
INVALID_TRANSACTIONID | 無效transaction_id | 請(qǐng)求參數(shù)未按指引進(jìn)行填寫 | 參數(shù)錯(cuò)誤,請(qǐng)重新檢查 |
PARAM_ERROR | 參數(shù)錯(cuò)誤 | 請(qǐng)求參數(shù)未按指引進(jìn)行填寫 | 請(qǐng)根據(jù)接口返回的詳細(xì)信息檢查您的程序 |
REQUIRE_POST_METHOD | 請(qǐng)使用post方法 | 未使用post傳遞參數(shù) | 請(qǐng)檢查請(qǐng)求參數(shù)是否通過post方法提交 |
SIGNERROR | 簽名錯(cuò)誤 | 參數(shù)簽名結(jié)果不正確 | 請(qǐng)檢查簽名參數(shù)和方法是否都符合簽名算法要求 |
REVERSE_EXPIRE | 訂單無法撤銷 | 訂單有7天的撤銷有效期,過期將不能撤銷 | 請(qǐng)檢查需要撤銷的訂單是否超過可撤銷有效期 |
INVALID_REQUEST | 無效請(qǐng)求 | 商戶系統(tǒng)異常導(dǎo)致 | 請(qǐng)檢查商戶權(quán)限是否異常、重復(fù)請(qǐng)求支付、證書錯(cuò)誤、頻率限制等 |
TRADE_ERROR | 訂單錯(cuò)誤 | 業(yè)務(wù)錯(cuò)誤導(dǎo)致交易失敗 | 請(qǐng)檢查用戶賬號(hào)是否異常、被風(fēng)控、是否符合規(guī)則限制等 |
USERPAYING | 用戶支付中 | 用戶正在支付中的訂單不允許撤銷 | 用戶正在支付中的訂單不允許撤銷,請(qǐng)稍后再試 |
注意:這是一個(gè)后端接口
# 10、更新支付結(jié)果
# 更新支付結(jié)果updateWxpayfacePayResult(2.13及以上版本不需要調(diào)用該接口)
接口作用:商戶側(cè)確認(rèn)支付結(jié)果后通知人臉SDK 更新支付結(jié)果,用戶確認(rèn)支付結(jié)果后返回wxpayfaceCallBack,刷臉支付界面關(guān)閉。
# 請(qǐng)求參數(shù)
除公共參數(shù)外,下方參數(shù)的代理設(shè)置可用于配置刷臉走商戶內(nèi)部代理。若不需要,則不用填寫。
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
appid | 是 | string | 商戶綁定的公眾號(hào)/小程序 appid |
mch_id | 是 | string | 商戶號(hào) |
store_id | 是 | string | 門店編號(hào) |
authinfo | 是 | string | 調(diào)用憑證。獲取方式參見: get_wxpayface_authinfo |
payresult | 是 | string | 支付結(jié)果。可取值:SUCCESS : 支付成功ERROR : 支付失敗 |
# 返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string | 錯(cuò)誤碼。公共定義見 公共錯(cuò)誤碼 |
err_code | 否 | Integer | 可為空,二級(jí)錯(cuò)誤碼,公共定義見 二級(jí)錯(cuò)誤碼 |
return_msg | 是 | string(128) | 對(duì)錯(cuò)誤碼的描述 |
# 請(qǐng)求示例
/**
* 更新支付結(jié)果
*
*/
HashMap payResultHash = new HashMap();
payResultHash.put("payresult", "");
....
WxPayFace.getInstance().updateWxpayfacePayResult(payResultHash, new IWxPayfaceCallback() {
@Override
public void response(final Map info) throws RemoteException {
if (info == null) {
showToast("調(diào)用返回為空, 請(qǐng)查看日志");
new RuntimeException("調(diào)用返回為空").printStackTrace();
return false;
}
String code = (String) info.get("return_code");
String msg = (String) info.get("return_msg");
if (TextUtils.equals(returnCode, "USER_QUERY_CANCEL")) {
mResultTxt.setText("請(qǐng)與商戶確認(rèn)支付結(jié)果");
} else {
mResultTxt.setText("支付完成");
}
}
});
注意:
- ◆ 商戶側(cè)確認(rèn)支付結(jié)果后通知人臉SDK 更新支付結(jié)果,用戶確認(rèn)支付結(jié)果后返回wxpayfaceCallBack,刷臉支付界面關(guān)閉
- ◆ 此接口已在2.13版本廢棄
# 11、釋放資源
# 釋放資源releaseWxpayface
接口作用:釋放人臉服務(wù),斷開連接。
接口使用規(guī)范:
- 聚合支付情況下:每次啟動(dòng)刷臉都需要initWxpayface,刷臉結(jié)束后需要調(diào)用releaseWxpayface(釋放攝像頭供其他刷臉支付平臺(tái)調(diào)用);
- 非聚合支付情況下:首次刷臉需要initWxpayface,刷臉結(jié)束后不需要調(diào)用releaseWxpayface,否則下次刷臉需要重新initWxpayface,影響啟動(dòng)耗時(shí);初始化之后第二次刷臉可以直接調(diào)用getWxpayfaceCode啟動(dòng)刷臉(在保證authinfo有效的情況下)。
# 請(qǐng)求示例
/**
*釋放資源
*
*/
WxPayFace.getInstance().releaseWxpayface(context);