# 六、支付分功能文檔
# 閱讀對象
對接刷臉+支付分業(yè)務(wù)的研發(fā)、產(chǎn)品、運營,需要有一定的API開發(fā)技術(shù)理解能力。
# 背景說明
支付分全稱“微信支付分”,是一款以微信委托代扣為基礎(chǔ)支付能力、以微信支付分為主要業(yè)務(wù)指標(biāo)的支付服務(wù)產(chǎn)品。
支付分目前主要應(yīng)用在免押租借、先享后付、智慧零售、免押速住等場景。當(dāng)用戶支付分達(dá)到商戶設(shè)置的分?jǐn)?shù)門欄時,即有機(jī)會獲得先享受服務(wù),后付款的權(quán)益。
刷臉支付分業(yè)務(wù)作為一種全新的體驗?zāi)J剑梢宰層脩粼诓挥檬謾C(jī)的情況下也能體驗先享受、后付款的服務(wù),真正做到了用戶與手機(jī)全程“0接觸”的目標(biāo)。
# 接入指引
刷臉支付分業(yè)務(wù),是通過刷臉的方式獲取用戶面容信息,并識別到用戶身份,從而為用戶開通并使用支付分的業(yè)務(wù)。商戶只需在客戶端安裝我們指定的SDK即可通過刷臉的方式獲取用戶的支付分授權(quán)信息,然后從后臺發(fā)起創(chuàng)建訂單、查詢訂單、完結(jié)訂單請求,從而完成交易過程。
刷臉支付分接入整體流程:
# 申請接入支付分
1. 申請接入
商戶向wechatpay_scoreBD@tencent.com發(fā)送郵件接入申請,微信側(cè)在3-5個工作日內(nèi)進(jìn)行評估并回復(fù)審核結(jié)果。申請需包含以下信息:
1)商戶基本信息
2)商戶簡介
3)需要使用微信支付分的產(chǎn)品方案或業(yè)務(wù)場景描述(請標(biāo)注“需人臉能力”)
4)商戶聯(lián)系方式
2. 簽署協(xié)議
商戶信息及業(yè)務(wù)場景審核通過后,微信側(cè)向商戶郵件發(fā)送協(xié)議模板,并完成協(xié)議的簽署。
# 對接刷臉支付分
業(yè)務(wù)時序圖:
# 1. 接入刷臉SDK
1.1 初始化刷臉支付 SDK:initWxpayface()
接口作用:對人臉SDK進(jìn)行初始化
請求參數(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 2.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 | 錯誤碼。公共定義見 公共錯誤碼 |
return_msg | 是 | string(128) | 對錯誤碼的描述 |
請求示例
/**
* 初始化
*
*/
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)用返回為空, 請查看日志");
new RuntimeException("調(diào)用返回為空").printStackTrace();
return false;
}
String code = (String) info.get("return_code");
String msg = (String) info.get("return_msg");
showToast("初始化完成");
}
});
建議:
- 您可以自定義一個Application,然后在自定義Application的onCreate()中調(diào)用initPayFace()完成人臉識別模塊的初始化 ;
- 您可以只在被調(diào)用人臉識別模塊的activity的onCreate()中完成initPayFace()的調(diào)用。
注意:目前我們沒有在initPayFace()中做app保活的自啟措施,所以當(dāng)您的應(yīng)用在啟動過程中遇到重啟/更新的問題,您必須重新調(diào)用initPayFace(),相信我們會在下一個最新的版本中對initPayFace()做進(jìn)一步的完善。
1.2 數(shù)據(jù)準(zhǔn)備: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
*
*/
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");
}
});
注意:請在初始化(initWxpayface)成功后獲取數(shù)據(jù)(getWxpayfaceRawdata)
1.3 獲取刷臉支付調(diào)用憑證
接口作用:獲取調(diào)用憑證
接口地址:https://payapp.weixin.qq.com/face/get_wxpayface_authinfo
請求參數(shù)
除公共參數(shù)外,下方參數(shù)的代理設(shè)置可用于配置刷臉走商戶內(nèi)部代理。若不需要,則不用填寫。
參數(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](#獲取數(shù)據(jù) getWxpayfaceRawdata)[獲取數(shù)據(jù) getWxpayfaceRawdata](#獲取數(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 | 取當(dāng)前時間,10位unix時間戳。 例如:1239878956 |
version | 是 | string | 版本號。固定為1 |
sign_type | 是 | string | 簽名類型,目前支持HMAC-SHA256和MD5,默認(rèn)為MD5 |
nonce_str | 是 | string(32) | 隨機(jī)字符串,不長于32位 |
sign | 是 | string | 參數(shù)簽名。詳見微信支付簽名算法 |
返回參數(shù)
參數(shù) | 必填 | 類型 | 說明 |
---|---|---|---|
return_code | 是 | string(16) | 錯誤碼。公共定義見 公共錯誤碼 |
return_msg | 是 | string(128) | 對錯誤碼的描述 |
authinfo | 是 | string(4096) | SDK調(diào)用憑證。用于調(diào)用SDK的人臉識別接口。參見[人臉識別 getWxpayfaceCode](#人臉識別 getWxpayfaceCode) |
expires_in | 否 | int | authinfo的有效時間, 單位秒。 例如: 3600在有效時間內(nèi), 對于同一臺終端設(shè)備,相同的參數(shù)的前提下(如:相同的公眾號、商戶號、 門店編號等),可以用同一個authinfo,多次調(diào)用SDK的getWxpayfaceCode接口。 |
nonce_str | 是 | string(32) | 隨機(jī)字符串 |
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),同一臺機(jī)具上重復(fù)使用。
注意:這是一個后端調(diào)用接口,請在獲取數(shù)據(jù)(getWxpayfaceRewdata)成功后獲取調(diào)用憑證get_wxpayface_authinfo(rawdata)
# 2. 對接刷臉支付分
刷臉查詢用戶支付分狀態(tài):getUserPayScoreStatus()
請求參數(shù)
字段名 | 變量名 | 類型 | 必填 | 描述 |
---|---|---|---|---|
公眾賬號ID | appid | string(32) | 是 | 商戶號綁定的公眾號/小程序appid**示例值:**wx8888888888888888 |
商戶號 | mch_id | string(32) | 是 | 微信支付分配給商戶的商戶號**示例值:**1900000109 |
商戶訂單號 | out_trade_no | string(32) | 是 | 商戶系統(tǒng)內(nèi)部服務(wù)訂單號,要求此參數(shù)只能由數(shù)字、大小寫字母_-|*組成,且在同一個商戶號下唯一。必須與創(chuàng)建支付分訂單時的 out_order_no **參數(shù)一致,否則影響筆數(shù)計算。****示例值:**2304203423948239423 |
接口調(diào)用憑證 | authinfo | string | 是 | 調(diào)用憑證。獲取方式參見: 《get_wxpayface_authinfo》 |
商戶簽約單號 | payscore_out_request_no | string(64) | 是 | 商戶簽約單號,用于刷臉支付 SDK 調(diào)用支付分授權(quán)接口。在用戶授權(quán)/解除授權(quán)成功時,支付分會攜帶此參數(shù)回調(diào)商戶。支付分回調(diào)通知接口見支付分文檔。**示例值:**1234323JKHDFE1243252 |
支付分服務(wù)ID | payscore_service_id | string(32) | 是 | 支付分 service_id,接入微信支付分時由微信支付分配。**示例值:**500001 |
是否請求 UnionId | ask_unionid | int | 否 | 是否需要生成用戶的 UnionId;傳入 1 為獲取,不傳或者傳入 0 為不獲取。只有傳入 1,后續(xù)在使用 face_sid 請求后臺接口時才能成功得到用戶的 UnionId. |
返回參數(shù)
字段名 | 變量名 | 類型 | 必填 | 描述 |
---|---|---|---|---|
返回狀態(tài)碼 | return_code | string(16) | 是 | 錯誤碼,枚舉值:SUCCESS:用戶已開通支付分并授權(quán)服務(wù)ERROR:人臉識別成功,但用戶開通支付分失敗,或授權(quán)服務(wù)失敗USER_CANCEL:用戶取消了識別或授權(quán)流程SCAN_PAYMENT:用戶選擇了掃碼使用服務(wù)示例值:SUCCESS |
錯誤碼 | err_code | int | 否 | 二級錯誤碼 |
返回信息 | return_msg | string(128) | 否 | 對錯誤碼的描述示例值: 如調(diào)用接口時必填的參數(shù)為空 |
用戶標(biāo)識 | openid | string(128) | 否 | 微信用戶在商戶對應(yīng)appid下的唯一標(biāo)識。openid(相當(dāng)于用戶身份),商戶可憑此創(chuàng)建支付分訂單。**示例值:**oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
用戶子標(biāo)識 | sub_openid | string(128) | 否 | 子商戶號下的 openid (服務(wù)商模式)。**示例值:**oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
接口調(diào)用憑證 | face_sid | string | 是 | 終端設(shè)備識別用戶成功后返回的憑證,商戶可憑此獲取用戶 UnionId |
2.1 創(chuàng)建支付分訂單
接口說明
適用對象:直連商戶
請求URL:https://api.mch.weixin.qq.com/v3/payscore/serviceorder
請求方式:POST
接口規(guī)則:https://wechatpay-api.gitbook.io/wechatpay-api-v3
path
指該參數(shù)為路徑參數(shù)
query
指該參數(shù)需在請求URL傳參
body
指該參數(shù)需在請求JSON傳參
請求參數(shù)
參數(shù)名 | 變量 | 類型[長度限制] | 必填 | 描述 |
---|---|---|---|---|
商戶服務(wù)訂單號 | out_order_no | string[1,32] | 是 | body 商戶系統(tǒng)內(nèi)部服務(wù)訂單號(不是交易單號),要求此參數(shù)只能由數(shù)字、大小寫字母_-|*組成,且在同一個商戶號下唯一。詳見[商戶訂單號]。 示例值:1234323JKHDFE1243252 |
公眾賬號ID | appid | string[1,32] | 是 | body 微信公眾平臺分配的與傳入的商戶號建立了支付綁定關(guān)系的appid,可在公眾平臺查看綁定關(guān)系,此參數(shù)需在本系統(tǒng)先進(jìn)行配置。 示例值:wxd678efh567hg6787 |
服務(wù)ID | service_id | string[1,32] | 是 | body 該服務(wù)ID有本接口對應(yīng)產(chǎn)品的權(quán)限。 示例值:500001 |
服務(wù)信息 | service_introduction | string[1,20] | 是 | body 服務(wù)信息,用于介紹本訂單所提供的服務(wù) ,當(dāng)參數(shù)長度超過20個字符時,報錯處理。 示例值:某某酒店 |
后付費項目 | post_payments | array | 否 | body 后付費項目列表,最多包含100條付費項目。 如果傳入,用戶側(cè)則顯示此參數(shù)。 |
后付費商戶優(yōu)惠 | post_discounts | array | 否 | body 后付費商戶優(yōu)惠列表,最多包含30條商戶優(yōu)惠。 如果傳入,用戶側(cè)則顯示此參數(shù)。 |
服務(wù)時間段 | time_range | object | 是 | body 服務(wù)時間范圍 |
服務(wù)位置 | location | object | 否 | body 服務(wù)位置信息 如果傳入,用戶側(cè)則顯示此參數(shù)。 |
訂單風(fēng)險金 | risk_fund | object | 是 | body 訂單風(fēng)險金信息 |
商戶數(shù)據(jù)包 | attach | string[1,256] | 否 | body 商戶數(shù)據(jù)包可存放本訂單所需信息,需要先urlencode后傳入。 當(dāng)商戶數(shù)據(jù)包總長度超出256字符時,報錯處理。 示例值:Easdfowealsdkjfnlaksjdlfkwqoi&wl3l2sald |
商戶回調(diào)地址 | notify_url | string[1,255] | 是 | body 商戶接收用戶確認(rèn)訂單和付款成功回調(diào)通知的地址。 示例值:https://api.test.com |
用戶標(biāo)識 | openid | string[1,128] | 條件選填 | body 微信用戶在商戶對應(yīng)appid下的唯一標(biāo)識。 免確認(rèn)訂單:必填 需確認(rèn)訂單:不填 示例值:oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
是否需要用戶確認(rèn) | need_user_confirm | bool | 是 | body 枚舉值: false:免確認(rèn)訂單 true:需確認(rèn)訂單 示例值:true |
請求示例
{
"out_order_no": "1234323JKHDFE1243252",
"appid": "wxd678efh567hg6787",
"service_id": "500001",
"service_introduction": "某某酒店",
"post_payments": [
{
"name": "就餐費用服務(wù)費",
"amount": 4000,
"description": "就餐人均100元服務(wù)費:100/小時",
"count": 1
}
],
"post_discounts": [
{
"name": "滿20減1元",
"description": "不與其他優(yōu)惠疊加"
}
],
"time_range": {
"start_time": "20091225091010",
"end_time": "20091225121010"
},
"location": {
"start_location": "嗨客時尚主題展餐廳",
"end_location": "嗨客時尚主題展餐廳"
},
"risk_fund": {
"name": "ESTIMATE_ORDER_COST",
"amount": 10000,
"description": "就餐的預(yù)估費用"
},
"attach": "Easdfowealsdkjfnlaksjdlfkwqoi&wl3l2sald",
"notify_url": "https://api.test.com",
"openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
"need_user_confirm": true,
}
返回參數(shù)
參數(shù)名 | 變量 | 類型[長度限制] | 必填 | 描述 |
---|---|---|---|---|
公眾賬號ID | appid | string[1,32] | 是 | 調(diào)用接口提交的公眾賬號ID。 示例值:wxd678efh567hg6787 |
商戶號 | mchid | string[1,32] | 是 | 調(diào)用接口提交的商戶號。 示例值:1230000109 |
商戶服務(wù)訂單號 | out_order_no | string[1,32] | 是 | 調(diào)用接口提交的商戶服務(wù)訂單號。 示例值:1234323JKHDFE1243252 |
服務(wù)ID | service_id | string[1,32] | 是 | 調(diào)用該接口提交的服務(wù)ID。 示例值:500001 |
服務(wù)信息 | service_introduction | string[1,20] | 是 | 服務(wù)信息,用于介紹本訂單所提供的服務(wù)。 示例值:某某酒店 |
服務(wù)訂單狀態(tài) | state | string[1,32] | 是 | 表示當(dāng)前單據(jù)狀態(tài)。枚舉值: 1、CREATED:商戶已創(chuàng)建服務(wù)訂單 2、DOING:服務(wù)訂單進(jìn)行中 3、DONE:服務(wù)訂單完成 4、REVOKED:商戶取消服務(wù)訂單 5、EXPIRED:服務(wù)訂單已失效 示例值:CREATED |
訂單狀態(tài)說明 | state_description | string (32) | 否 | 對服務(wù)訂單"進(jìn)行中"狀態(tài)的附加說明。 1、USER_CONFIRM:用戶確認(rèn) 2、MCH_COMPLETE:商戶完結(jié) 示例值:MCH_COMPLETE |
后付費項目 | post_payments | array | 否 | 后付費項目列表,最多包含100條付費項目。 如果傳入,用戶側(cè)則顯示此參數(shù)。 |
后付費商戶優(yōu)惠 | post_discounts | array | 否 | 后付費商戶優(yōu)惠,最多包含30條付費項目。 如果傳入,用戶側(cè)則顯示此參數(shù)。 |
訂單風(fēng)險金 | risk_fund | object | 是 | 訂單風(fēng)險金信息 |
服務(wù)時間段 | time_range | object | 是 | 服務(wù)時間范圍 |
服務(wù)位置 | location | object | 否 | 服務(wù)使用信息。 如果傳入,用戶側(cè)則顯示此參數(shù)。 |
商戶數(shù)據(jù)包 | attach | string[1,256] | 否 | 商戶數(shù)據(jù)包,可存放本訂單所需信息,需要先urlencode后傳入,總長度不大于256字符,超出報錯處理。 示例值:Easdfowealsdkjfnlaksjdlfkwqoi&wl3l2sald |
商戶回調(diào)地址 | notify_url | string[1,255] | 否 | 商戶接收用戶確認(rèn)訂單或扣款成功回調(diào)通知的地址。 示例值:https://api.test.com |
微信支付服務(wù)訂單號 | order_id | string[1,64] | 是 | 微信支付服務(wù)訂單號,每個微信支付服務(wù)訂單號與商戶號下對應(yīng)的商戶服務(wù)訂單號一一對應(yīng)。 示例值:15646546545165651651 |
跳轉(zhuǎn)微信側(cè)小程序訂單數(shù)據(jù) | package | string[1,300] | 是 | 用于跳轉(zhuǎn)到微信側(cè)小程序訂單數(shù)據(jù),跳轉(zhuǎn)到微信側(cè)小程序傳入。該數(shù)據(jù)1小時內(nèi)有效。 示例值:DJIOSQPYWDxsjdldeuwhdodwxasd_dDiodnwjh9we |
返回示例
{
"appid": "wxd678efh567hg6787",
"mchid": "1230000109",
"out_order_no": "1234323JKHDFE1243252",
"service_id": "500001",
"service_introduction": "某某酒店",
"state": "CREATED",
"state_description": "MCH_COMPLETE",
"post_payments": [
{
"name": "就餐費用服務(wù)費",
"amount": 4000,
"description": "就餐人均100元服務(wù)費:100/小時",
"count": 1
}
],
"post_discounts": [
{
"name": "滿20減1元",
"description": "不與其他優(yōu)惠疊加"
}
],
"risk_fund": {
"name": " ESTIMATE_ORDER_COST",
"amount": 10000,
"description": "就餐的預(yù)估費用"
},
"time_range": {
"start_time": "20091225091010",
"end_time": "20091225121010"
},
"location": {
"start_location": "嗨客時尚主題展餐廳",
"end_location": "嗨客時尚主題展餐廳"
},
"attach": "Easdfowealsdkjfnlaksjdlfkwqoi&wl3l2sald",
"notify_url": "https://api.test.com",
"order_id": "15646546545165651651",
"package": " DJIOSQPYWDxsjdldeuwhdodwxasd_dDiodnwjh9we "
}
錯誤碼
狀態(tài)碼 | 錯誤碼 | 描述 | 解決方案 |
---|---|---|---|
500 | SYSTEM_ERROR | 系統(tǒng)錯誤 | 5開頭的狀態(tài)碼都為系統(tǒng)問題,請使用相同參數(shù)稍后重新調(diào)用 |
400 | PARAM_ERROR | 參數(shù)錯誤 | 根據(jù)錯誤提示,傳入正確參數(shù) |
403 | NO_AUTH | 商戶信息不合法 | 登錄商戶平臺核對,傳入正確信息 |
429 | FREQUENCY_LIMITED | 頻率超限 | 請求量不要超過接口調(diào)用頻率限制 |
400 | INVALID_REQUEST | 請求參數(shù)符合參數(shù)格式,但不符合業(yè)務(wù)規(guī)則 | 請確認(rèn)相同單號是否使用了不同的參數(shù) |
404 | ORDER_NOT_ EXIST | 訂單不存在 | 確認(rèn)入?yún)ⅲ瑐魅胝_單據(jù) |
400 | INVALID_ORDER_STATE | 單據(jù)狀態(tài)錯誤 | 確認(rèn)操作是否符合流程 |
400 | ORDER_CANCELED | 單據(jù)已取消 | 當(dāng)前狀態(tài)無需操作 |
400 | ORDER_DONE | 訂單已完成 | 當(dāng)前狀態(tài)無需操作 |
2.2 完結(jié)支付分訂單
完結(jié)微信支付分訂單。用戶使用完服務(wù)完成后,商戶可通過此接口完結(jié)訂單。
特別說明
完結(jié)接口調(diào)用成功后,微信支付將自動發(fā)起免密代扣。 若扣款失敗,微信支付將自動再次發(fā)起免密代扣(按照一定頻次),直到扣成功為止。
接口說明
適用對象:直連商戶
請求URL:https://api.mch.weixin.qq.com/v3/payscore/serviceorder/{out_order_no}/complete
請求方式:POST
前置條件:服務(wù)訂單狀態(tài)為“進(jìn)行中”且訂單狀態(tài)說明需為[USER_CONFIRM:用戶確認(rèn)]
接口規(guī)則:https://wechatpay-api.gitbook.io/wechatpay-api-v3
path
指該參數(shù)為路徑參數(shù)
query
指該參數(shù)需在請求URL傳參
body
指該參數(shù)需在請求JSON傳參
請求參數(shù)
參數(shù)名 | 變量 | 類型[長度限制] | 必填 | 描述 |
---|---|---|---|---|
商戶服務(wù)訂單號 | out_order_no | string[1,32] | 是 | path 商戶系統(tǒng)內(nèi)部服務(wù)訂單號(不是交易單號),與創(chuàng)建訂單時一致 示例值:1234323JKHDFE1243252 |
公眾賬號ID | appid | string[1,32] | 是 | body 微信公眾平臺分配的與傳入的商戶號建立了支付綁定關(guān)系的appid,可在公眾平臺查看綁定關(guān)系,此參數(shù)需在本系統(tǒng)先進(jìn)行配置。 示例值:wxd678efh567hg6787 |
服務(wù)ID | service_id | string[1,32] | 是 | body 服務(wù)訂單的主鍵,唯一定義此資源的標(biāo)識 示例值:500001 |
后付費項目 | post_payments | array | 是 | body 后付費項目列表,最多包含100條付費項目 |
后付費商戶優(yōu)惠 | post_discounts | array | 否 | body 后付費商戶優(yōu)惠列表,最多包含30條商戶優(yōu)惠 如果傳入,用戶側(cè)則顯示此參數(shù) |
總金額 | total_amount | int64 | 是 | body 1、金額:數(shù)字,必須≥0(單位:分),只能為整數(shù),詳見支付金額。 2、總金額 =(完結(jié)付費項目1…+完結(jié)付費項目n)-(完結(jié)商戶優(yōu)惠項目1…+完結(jié)商戶優(yōu)惠項目n) 3、總金額上限 1)【評估不通過:交押金】模式:總金額≤創(chuàng)單時填寫的“訂單風(fēng)險金額” 2)【評估不通過:拒絕】模式:總金額≤“每個服務(wù)ID的風(fēng)險金額上限” 示例值:50000 |
服務(wù)時間段 | time_range | object | 條件選填 | body 服務(wù)時間范圍,創(chuàng)建訂單未填寫服務(wù)結(jié)束時間,則完結(jié)的時候,服務(wù)結(jié)束時間必填 如果傳入,用戶側(cè)則顯示此參數(shù)。 |
服務(wù)位置 | location | object | 否 | body 服務(wù)位置 如果傳入,用戶側(cè)則顯示此參數(shù)。 |
微信支付服務(wù)分賬標(biāo)記 | profit_sharing | bool | 否 | body 完結(jié)訂單分賬接口標(biāo)記。分賬開通流程,詳見 false:不分賬,默認(rèn):false true:分賬。 示例值:false |
訂單優(yōu)惠標(biāo)記 | goods_tag | string(32) | 否 | body 訂單優(yōu)惠標(biāo)記,代金券或立減金優(yōu)惠的參數(shù),說明詳見代金券或立減金優(yōu)惠 示例值:goods_tag |
請求示例
{
"appid": "wxd678efh567hg6787",
"service_id": "500001",
"post_payments": [
{
"name": "就餐費用服務(wù)費",
"amount": 4000,
"description": "就餐人均100元服務(wù)費:100/小時",
"count": 1
}
],
"post_discounts":[
{
"name": "滿20減1元",
"description": "不與其他優(yōu)惠疊加",
"amount": 4000
}
],
"total_amount": 3900,
"time_range": {
"start_time": "20091225091010",
"end_time": "20091225121010"
},
"location": {
"end_location": "嗨客時尚主題展餐廳"
},
"profit_sharing": false
}
返回參數(shù)
參數(shù)名 | 變量 | 類型[長度限制] | 必填 | 描述 |
---|---|---|---|---|
公眾賬號ID | appid | string[1,32] | 是 | 調(diào)用接口提交的公眾賬號ID 示例值:wxd678efh567hg6787 |
商戶號 | mchid | string[1,32] | 是 | 調(diào)用接口提交的商戶號 示例值:1230000109 |
商戶服務(wù)訂單號 | out_order_no | string[1,32] | 是 | 調(diào)用接口提交的商戶服務(wù)訂單號 示例值:1234323JKHDFE1243252 |
服務(wù)ID | service_id | string[1,32] | 是 | 調(diào)用該接口提交的服務(wù)ID 示例值:500001 |
服務(wù)信息 | service_introduction | string[1,20] | 是 | 服務(wù)信息,用于介紹本訂單所提供的服務(wù) 示例值:某某酒店 |
服務(wù)訂單狀態(tài) | state | string[1,32] | 是 | 表示當(dāng)前單據(jù)狀態(tài)。 1、CREATED:商戶已創(chuàng)建服務(wù)訂單 2、DOING:服務(wù)訂單進(jìn)行中 3、DONE:服務(wù)訂單完成 4、REVOKED:商戶取消服務(wù)訂單 5、EXPIRED:服務(wù)訂單已失效,"商戶已創(chuàng)建服務(wù)訂單"狀態(tài)超過30天未變動,則訂單失效 示例值:CREATED |
訂單狀態(tài)說明 | state_description | string[1,32] | 否 | 對服務(wù)訂單"進(jìn)行中"狀態(tài)的附加說明 USER_CONFIRM:用戶確認(rèn) MCH_COMPLETE:商戶完結(jié) 示例值:MCH_COMPLETE |
商戶收款總金額 | total_amount | int64 | 是 | 總金額,大于等于0的數(shù)字,單位為分,只能為整數(shù),詳見支付金額。 此參數(shù)需滿足:總金額=后付費項目金額之和-后付費商戶優(yōu)惠項目金額之和,且小于等于訂單風(fēng)險金額。取消訂單時,該字段必須為0。 示例值:40000 |
后付費項目 | post_payments | array | 是 | 后付費項目列表,最多包含100條付費項目 |
后付費商戶優(yōu)惠 | post_discounts | array | 否 | 后付費商戶優(yōu)惠,最多包含30條付費項目; 如果傳入,用戶側(cè)則顯示此參數(shù) |
訂單風(fēng)險金 | risk_fund | object | 是 | 訂單風(fēng)險金信息 |
服務(wù)時間段 | time_range | object | 否 | 服務(wù)時間范圍; 如果傳入,用戶側(cè)則顯示此參數(shù) |
服務(wù)位置 | location | object | 否 | 服務(wù)使用信息; 如果傳入,用戶側(cè)則顯示此參數(shù) |
微信支付服務(wù)訂單號 | order_id | string[1,64] | 是 | 微信支付服務(wù)訂單號,每個微信支付服務(wù)訂單號與商戶號下對應(yīng)的商戶服務(wù)訂單號一一對應(yīng) 示例值:15646546545165651651 |
是否需要收款 | need_collection | bool | 否 | true:微信支付分代收款 false:無需微信支付分代收款 示例值:true |
返回示例
{
"appid": "wxd678efh567hg6787",
"mchid": "1230000109",
"out_order_no": "1234323JKHDFE1243252",
"service_id": "500001",
"service_introduction": "某某酒店",
"state": "DOING",
"state_description": "",
"total_amount": 3900,
"post_payments": [
{
"name": "就餐費用服務(wù)費",
"amount": 1,
"description": "就餐人均100元服務(wù)費:100/小時",
"count": 1
}
],
"post_discounts": [
{
"name": "滿20減1元",
"description": "不與其他優(yōu)惠疊加",
"amount": 1
}
],
"risk_fund": {
"name": "ESTIMATE_ORDER_COST",
"amount": 4000,
"description": "就餐的預(yù)估費用"
},
"time_range": {
"start_time": "20091225091010",
"end_time": "20091225121010"
},
"location": {
"start_location": "嗨客時尚主題展餐廳",
"end_location": "嗨客時尚主題展餐廳"
},
"order_id": "15646546545165651651",
"need_collection": true
}
錯誤碼
狀態(tài)碼 | 錯誤碼 | 描述 | 解決方案 |
---|---|---|---|
500 | SYSTEM_ERROR | 系統(tǒng)錯誤 | 5開頭的狀態(tài)碼都為系統(tǒng)問題,請使用相同參數(shù)稍后重新調(diào)用 |
400 | PARAM_ERROR | 參數(shù)錯誤 | 根據(jù)錯誤提示,傳入正確參數(shù) |
403 | NO_AUTH | 商戶信息不合法 | 登錄商戶平臺核對,傳入正確信息 |
429 | FREQUENCY_LIMITED | 頻率超限 | 請求量不要超過接口調(diào)用頻率限制 |
400 | INVALID_REQUEST | 請求參數(shù)符合參數(shù)格式,但不符合業(yè)務(wù)規(guī)則 | 請確認(rèn)相同單號是否使用了不同的參數(shù) |
404 | ORDER_NOT_ EXIST | 訂單不存在 | 確認(rèn)入?yún)ⅲ瑐魅胝_單據(jù) |
400 | INVALID_ORDER_STATE | 單據(jù)狀態(tài)錯誤 | 確認(rèn)操作是否符合流程 |
400 | ORDER_CANCELED | 單據(jù)已取消 | 當(dāng)前狀態(tài)無需操作 |
400 | ORDER_DONE | 訂單已完成 | 當(dāng)前狀態(tài)無需操作 |
2.3 同步服務(wù)訂單信息
由于收款商戶進(jìn)行的某些“線下操作”會導(dǎo)致微信支付側(cè)的訂單狀態(tài)與實際情況不符。例如,用戶通過線下付款的方式已經(jīng)完成支付,而微信支付側(cè)并未支付成功,此時可能導(dǎo)致用戶重復(fù)支付。因此商戶需要通過訂單同步接口將訂單狀態(tài)同步給微信支付,修改訂單在微信支付系統(tǒng)中的狀態(tài)。
接口說明
適用對象:直連商戶
請求URL: https://api.mch.weixin.qq.com/v3/payscore/serviceorder/{out_order_no}/sync
請求方式:POST
接口規(guī)則:https://wechatpay-api.gitbook.io/wechatpay-api-v3
前提條件:同步商戶渠道收款成功信息時,即場景類型=“Order_Paid”,訂單的狀態(tài)需為[MCH_COMPLETE:商戶完結(jié)訂單]
path
指該參數(shù)為路徑參數(shù)
query
指該參數(shù)需在請求URL傳參
body
指該參數(shù)需在請求JSON傳參
請求參數(shù)
參數(shù)名 | 變量 | 類型[長度限制] | 必填 | 描述 |
---|---|---|---|---|
商戶服務(wù)訂單號 | out_order_no | string[1,32] | 是 | path 商戶系統(tǒng)內(nèi)部訂單號(不是交易單號),要求此參數(shù)只能由數(shù)字、大小寫字母_-|*組成,且在同一個商戶號下唯一,詳見「商戶訂單號」,需要和創(chuàng)建訂單的商戶服務(wù)訂單號一致。 示例值:1234323JKHDFE1243252 |
公眾賬號ID | appid | string[1,32] | 是 | body 微信公眾平臺分配的與傳入的商戶號建立了支付綁定關(guān)系的appid,可在公眾平臺查看綁定關(guān)系。 此參數(shù)需在本系統(tǒng)先進(jìn)行配置,并與創(chuàng)建訂單時的appid保持一致。 示例值:wxd678efh567hg6787 |
服務(wù)ID | service_id | string[1,32] | 是 | body 該服務(wù)ID有本接口對應(yīng)產(chǎn)品的權(quán)限,需要與創(chuàng)建訂單時保持一致。 示例值:500001 |
場景類型 | type | string[1,32] | 是 | body 場景類型為“Order_Paid”,字符串表示“訂單收款成功” 。 示例值:Order_Paid |
內(nèi)容信息詳情 | detail | object | 否 | body 場景類型為Order_Paid時,為必填項。 |
請求示例
{
"appid": "wxd678efh567hg6787",
"service_id": "500001",
"type": "Order_Paid",
"detail": {
"paid_time": "20091225091210"
}
}
返回參數(shù)
參數(shù)名 | 變量 | 類型[長度限制] | 必填 | 描述 |
---|---|---|---|---|
公眾賬號ID | appid | string[1,32] | 是 | 調(diào)用接口提交的公眾賬號ID。 示例值:wxd678efh567hg6787 |
商戶號 | mchid | string[1,32] | 是 | 調(diào)用接口提交的商戶號。 示例值:1230000109 |
商戶服務(wù)訂單號 | out_order_no | string[1,32] | 是 | 調(diào)用接口提交的商戶服務(wù)訂單號。 示例值:1234323JKHDFE1243252 |
服務(wù)ID | service_id | string[1,32] | 是 | 調(diào)用該接口提交的服務(wù)ID。 示例值:500001 |
服務(wù)信息 | service_introduction | string[1,20] | 是 | 服務(wù)信息,用于介紹本訂單所提供的服務(wù)。 示例值:某某酒店 |
服務(wù)訂單狀態(tài) | state | string[1,32] | 是 | 表示當(dāng)前單據(jù)狀態(tài)。枚舉值: CREATED:商戶已創(chuàng)建服務(wù)訂單 DOING:服務(wù)訂單進(jìn)行中 DONE:服務(wù)訂單完成 REVOKED:商戶取消服務(wù)訂單 EXPIRED:服務(wù)訂單已失效,"商戶已創(chuàng)建服務(wù)訂單"狀態(tài)超過30天未變動,則訂單失效 示例值:CREATED |
訂單狀態(tài)說明 | state_description | string[1,32] | 否 | 對服務(wù)訂單"進(jìn)行中"狀態(tài)的附加說明。枚舉值: USER_CONFIRM:用戶確認(rèn) MCH_COMPLETE:商戶完結(jié) 示例值:MCH_COMPLETE |
商戶收款總金額 | total_amount | int64 | 否 | 總金額,大于等于0的數(shù)字,單位為分,只能為整數(shù),詳見支付金額。 此參數(shù)需滿足:總金額=后付費項目金額之和-后付費商戶優(yōu)惠項目金額之和,且小于等于訂單風(fēng)險金額。取消訂單時,該字段必須為0。 示例值:40000 |
后付費項目 | post_payments | array | 否 | 后付費項目列表,最多包含100條付費項目。 |
后付費商戶優(yōu)惠 | post_discounts | array | 否 | 后付費商戶優(yōu)惠,最多包含30條付費項目。 |
訂單風(fēng)險金 | risk_fund | object | 否 | 訂單風(fēng)險金信息 |
服務(wù)時間段 | time_range | object | 否 | 服務(wù)時間范圍 |
服務(wù)位置 | location | object | 否 | 服務(wù)使用信息 |
商戶數(shù)據(jù)包 | attach | string[1,256] | 否 | 商戶數(shù)據(jù)包,可存放本訂單所需信息,需要先urlencode后傳入,總長度不大于256字符,超出報錯處理。 示例值:Easdfowealsdkjfnlaksjdlfkwqoi&wl3l2sald |
商戶回調(diào)地址 | notify_url | string[1,255] | 否 | 商戶接收用戶確認(rèn)訂單或扣款成功回調(diào)通知的地址。 示例值:https://api.test.com |
微信支付服務(wù)訂單號 | order_id | string[1,64] | 是 | 微信支付服務(wù)訂單號,每個微信支付服務(wù)訂單號與商戶號下對應(yīng)的商戶服務(wù)訂單號一一對應(yīng)。 示例值:15646546545165651651 |
是否需要收款 | need_collection | bool | 否 | true:微信支付分代收款 false:無需微信支付分代收款 示例值:true |
收款信息 | collection | object | 否 | 收款信息 |
返回示例
{
"appid": "wxd678efh567hg6787",
"mchid": "1230000109",
"service_id": "500001",
"out_order_no": "1234323JKHDFE1243252",
"service_introduction": "某某酒店",
"state": "CREATED",
"state_description": "MCH_COMPLETE",
"total_amount": 3900,
"post_payments": [
{
"name": "就餐費用服務(wù)費",
"amount": 4000,
"description": "就餐人均100元服務(wù)費:100/小時",
"count": 1
}
],
"post_discounts": [
{
"name": "滿20減1元",
"description": "不與其他優(yōu)惠疊加",
"amount": 100
}
],
"risk_fund": {
"name": "ESTIMATE_ORDER_COST",
"amount": 10000,
"description": "就餐的預(yù)估費用"
},
"time_range": {
"start_time": "20091225091010",
"end_time": "20091225121010"
},
"location": {
"start_location": "嗨客時尚主題展餐廳",
"end_location": "嗨客時尚主題展餐廳"
},
"attach": "Easdfowealsdkjfnlaksjdlfkwqoi&wl3l2sald",
"notify_url": "https://api.test.com",
"order_id": "15646546545165651651",
"need_collection": true,
"collection": {
"state": "USER_PAID",
"total_amount": 3900,
"paying_amount": 0,
"paid_amount": 3900,
"details": [
{
"amount": 10000,
"paid_type": "NEWTON",
"paid_time": "20091225091210",
"transaction_id ": "15646546545165651651"
}
]
}
}
錯誤碼
狀態(tài)碼 | 錯誤碼 | 描述 | 解決方案 |
---|---|---|---|
500 | SYSTEM_ERROR | 系統(tǒng)錯誤 | 5開頭的狀態(tài)碼都為系統(tǒng)問題,請使用相同參數(shù)稍后重新調(diào)用 |
400 | PARAM_ERROR | 參數(shù)錯誤 | 根據(jù)錯誤提示,傳入正確參數(shù) |
403 | NO_AUTH | 商戶信息不合法 | 登錄商戶平臺核對,傳入正確信息 |
429 | FREQUENCY_LIMITED | 頻率超限 | 請求量不要超過接口調(diào)用頻率限制 |
400 | INVALID_REQUEST | 請求參數(shù)符合參數(shù)格式,但不符合業(yè)務(wù)規(guī)則 | 請確認(rèn)相同單號是否使用了不同的參數(shù) |
404 | ORDER_NOT_ EXIST | 訂單不存在 | 確認(rèn)入?yún)ⅲ瑐魅胝_單據(jù) |
400 | INVALID_ORDER_STATE | 單據(jù)狀態(tài)錯誤 | 確認(rèn)操作是否符合流程 |
400 | ORDER_CANCELED | 單據(jù)已取消 | 當(dāng)前狀態(tài)無需操作 |
400 | ORDER_DONE | 訂單已完成 | 當(dāng)前狀態(tài)無需操作 |
# 3. 獲取用戶Unionid
GET /v3/facemch/users/{face_sid}
商戶可以根據(jù)face_sid查詢用戶UnionId。
請求參數(shù)
變量名 | 所處位置 | 數(shù)據(jù)類型 | 必填 | 限制條件 | 描述 | 示例 |
---|---|---|---|---|---|---|
face_sid | path | string | true | 終端設(shè)備識別用戶成功后返回的憑證,getWxpayfaceUserInfo接口返回的token字段 | aabbccdd12345 | |
info_type | query | string | true | 標(biāo)識本次請求獲取的信息類型 | ASK_UNIONID:獲取用戶union_id | |
appid | query | string | true | 微信分配的公眾賬號ID | wx2b029c08a6233333 | |
sub_mchid | query | string | false | 微信支付分配的子商戶號,服務(wù)商模式下必填 | 123456789 | |
sub_appid | query | string | false | 微信分配的子商戶公眾賬號ID | wx2b029c08a6255555 |
返回結(jié)果
狀態(tài)碼 | 含義 | 描述 | 數(shù)據(jù)類型 |
---|---|---|---|
200 | OK | 處理成功 | JSON |
應(yīng)答樣例
200 Response
{
? "union_id": "abcdefg111"
}
# 方案驗收
1. 產(chǎn)品方案驗收,需提供以下相關(guān)信息:
- 商戶側(cè)業(yè)務(wù)全流程的錄屏
- 商戶提供APP(包括IOS和安卓)、小程序或h5的驗收環(huán)境,微信側(cè)將在驗收環(huán)境內(nèi)進(jìn)行驗收確認(rèn)。
2. 確認(rèn)灰度時間并在約定時間灰度上線
3. 驗收完成后微信側(cè)即完成支付分配置,產(chǎn)品正式上線。
郵件審核
請將郵件發(fā)送至以下郵箱: wxfacepay_help@tencent.com