公眾號(hào)簽約
應(yīng)用場(chǎng)景
商戶(hù)可以通過(guò)請(qǐng)求此接口喚起微信委托代扣的頁(yè)面，頁(yè)面樣例見(jiàn)案例與規(guī)范。
用戶(hù)在微信的頁(yè)面中完成代扣簽約后，微信會(huì)同時(shí)將簽約信息通過(guò)異步通知的方式通知給商戶(hù)后臺(tái)。如果用戶(hù)放棄簽約或簽約失敗則不通知。
接口調(diào)用請(qǐng)求說(shuō)明
| 請(qǐng)求Url | https://api.mch.weixin.qq.com/papay/entrustweb |
|---|---|
| 是否需要證書(shū) | 否 |
| 請(qǐng)求方式 | GET |
請(qǐng)求參數(shù)
| 字段名 | 字段 | 必填 | 類(lèi)型 | 示例值 | 說(shuō)明 |
|---|---|---|---|---|---|
| 請(qǐng)求appid | appid | 是 | String(32) | wxcbda96de0b165486 | appid是商戶(hù)在微信申請(qǐng)公眾號(hào)賬號(hào)ID，登錄平臺(tái)為mp.weixin.qq.com |
| 商戶(hù)號(hào) | mch_id | 是 | String(32) | 1200009811 | 商戶(hù)號(hào)是商戶(hù)在微信申請(qǐng)微信支付成功后分配的賬號(hào)ID，登錄平臺(tái)為www.tg885.com |
| 模板id | plan_id | 是 | String(28) | 12535 | 協(xié)議模板id，設(shè)置路徑見(jiàn)開(kāi)發(fā)步驟。 |
| 簽約協(xié)議號(hào) | contract_code | 是 | String(128) | 100000 | 商戶(hù)側(cè)的簽約協(xié)議號(hào)，由商戶(hù)生成 |
| 請(qǐng)求序列號(hào) | request_serial | 是 | int64 | 1000 | 商戶(hù)請(qǐng)求簽約時(shí)的序列號(hào)，要求唯一性。序列號(hào)主要用于排序，不作為查詢(xún)條件，純數(shù)字,范圍不能超過(guò)int64的范圍（9223372036854775807）。 |
| 用戶(hù)賬戶(hù)展示名稱(chēng) | contract_display_account | 是 | String(128) | 微信代扣 | 簽約用戶(hù)的名稱(chēng)，用于頁(yè)面展示，，參數(shù)值不支持UTF8非3字節(jié)編碼的字符，例如表情符號(hào)，所以請(qǐng)勿傳微信昵稱(chēng)到該字段 |
| 回調(diào)通知url | notify_url | 是 | String | https://weixin.qq.com | 用于接收簽約成功消息的回調(diào)通知地址，以http或https開(kāi)頭。請(qǐng)對(duì)notify_url參數(shù)值進(jìn)行encode處理,注意是對(duì)參數(shù)值進(jìn)行encode，例如參數(shù)為notify_url=“https://weixin.qq.com”，則需要encode的內(nèi)容為https://weixin.qq.com |
| 版本號(hào) | version | 是 | string | 1.0 | 固定值1.0 |
簽名 |
sign |
是 |
String(32) |
C380BEC2BFD727A4B6845133519F3AD6 |
詳見(jiàn)簽名生成算法 |
| 時(shí)間戳 | timestamp | 是 | String(10) | 1414488825 | 系統(tǒng)當(dāng)前時(shí)間，10位 |
以下字段為非必填項(xiàng)，用來(lái)控制簽約頁(yè)面結(jié)束后的返回路徑（不傳此參數(shù)，則簽約完成后停留在微信內(nèi)）: | |||||
返回web |
return_web |
否 |
int |
1 |
1表示返回簽約頁(yè)面的referrer url, 不填或獲取不到referrer則不返回; 跳轉(zhuǎn)referrer url時(shí)會(huì)自動(dòng)帶上參數(shù)from_wxpay=1 |
簽約請(qǐng)求數(shù)據(jù)示例：
返回參數(shù)（異步返回）
簽約成功后，微信會(huì)把相關(guān)簽約結(jié)果異步發(fā)送給商戶(hù)，返回的url為調(diào)用上述簽約接口時(shí)填寫(xiě)的notify_url字段。商戶(hù)在收到簽約結(jié)果通知后，需進(jìn)行接收處理并返回應(yīng)答
對(duì)后臺(tái)通知交互時(shí)，如果微信收到商戶(hù)的應(yīng)答不是成功或超時(shí)，微信認(rèn)為通知失敗，微信會(huì)通過(guò)一定的策略定期重新發(fā)起通知,盡可能提高通知的成功率，但微信不保證通知最終能成功。
（通知頻率為15/15/30/180/1800/1800/1800/1800/3600，單位：秒）
由于存在重新發(fā)送后臺(tái)通知的情況，因此同樣的通知可能會(huì)多次發(fā)送給商戶(hù)系統(tǒng)。商戶(hù)系統(tǒng)必須能夠正確處理重復(fù)的通知。
推薦的做法是，當(dāng)收到通知進(jìn)行處理時(shí)，首先檢查對(duì)應(yīng)業(yè)務(wù)數(shù)據(jù)的狀態(tài)，判斷該通知是否已經(jīng)處理過(guò)，如果沒(méi)有處理過(guò)再進(jìn)行處理，如果處理過(guò)直接返回結(jié)果成功。在對(duì)業(yè)務(wù)數(shù)據(jù)進(jìn)行狀態(tài)檢查和處理之前，要采用數(shù)據(jù)鎖進(jìn)行并發(fā)控制，以避免函數(shù)重入造成的數(shù)據(jù)混亂。
| 字段名 | 變量名 | 必填 | 示例值 | 類(lèi)型 | 說(shuō)明 |
|---|---|---|---|---|---|
返回狀態(tài)碼 |
return_code |
是 |
SUCCESS |
String(16) |
SUCCESS/FAIL |
返回信息 |
return_msg |
否 |
簽名失敗 |
String(128) |
返回信息，如非空，為錯(cuò)誤原因 |
| 以下字段在return_code為SUCCESS的時(shí)候返回 | |||||
業(yè)務(wù)結(jié)果 |
result_code |
是 |
SUCCESS |
String(16) |
SUCCESS/FAIL |
| 以下字段在return_code 和result_code都為SUCCESS的時(shí)候有返回 | |||||
商戶(hù)號(hào) |
mch_id |
是 |
10000098 |
String(32) |
微信支付分配的商戶(hù)號(hào) |
簽約協(xié)議號(hào) |
contract_code |
是 |
100001256 |
String(128) |
簽約協(xié)議號(hào) |
模板id |
plan_id |
是 |
123 |
String |
協(xié)議模板id |
用戶(hù)標(biāo)識(shí) |
openid |
是 |
onqOjjmM1tad-3ROpncN-yUfa6ua |
String(32) |
Appid下，用戶(hù)的唯一標(biāo)識(shí) |
簽名 |
sign |
是 |
C380BEC2BFD727A4B6845133519F3AD6 |
String(32) |
詳見(jiàn)簽名生成算法 |
變更類(lèi)型 |
change_type |
是 |
ADD |
String(32) |
有兩個(gè)變更類(lèi)型取值: |
操作時(shí)間 |
operate_time |
是 |
2015-07-01 10:00:00 |
String |
操作時(shí)間 |
委托代扣協(xié)議id |
contract_id |
是 |
Wx15463511252015071056489715 |
String（32） |
簽約成功后，微信返回的委托代扣協(xié)議id |
協(xié)議到期時(shí)間 |
contract_expired_time |
否 |
2016-07-01 10:00:00 |
String |
協(xié)議到期時(shí)間，當(dāng)change_type為ADD時(shí)有返回 |
協(xié)議解約方式 |
contract_termination_mode |
否 |
3 |
int | 當(dāng)change_type為DELETE時(shí)有返回 |
請(qǐng)求序列號(hào) |
request_serial |
是 |
1695 |
int64 |
商戶(hù)請(qǐng)求簽約時(shí)的序列號(hào)，商戶(hù)側(cè)須唯一。序列號(hào)主要用于排序，不作為查詢(xún)條件，純數(shù)字,范圍不能超過(guò)int64的范圍（9223372036854775807）。 |
示例：
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<result_code><![CDATA[SUCCESS]]></result_code>
<sign><![CDATA[C380BEC2BFD727A4B6845133519F3AD6]]></sign>
<mch_id>10010404</mch_id>
<contract_code>100001256</contract_code>
<openid><![CDATA[onqOjjmM1tad-3ROpncN-yUfa6ua]]></openid>
<plan_id><![CDATA[123]]></plan_id>
<change_type><![CDATA[ADD]]></change_type>
<operate_time><![CDATA[2015-07-01 10:00:00]]></operate_time>
<contract_id><![CDATA[Wx15463511252015071056489715]]></contract_id>
</xml>
商戶(hù)需返回參數(shù)
由于微信會(huì)多次通知商戶(hù)服務(wù)器關(guān)于用戶(hù)簽約的結(jié)果和相關(guān)信息，為了避免給商戶(hù)服務(wù)器造成過(guò)大的壓力，請(qǐng)?jiān)诘玫轿⑿藕灱s結(jié)果通知之后，返回以下內(nèi)容。（請(qǐng)求方式：post）
| 字段名 | 變量名 | 必填 | 示例值 | 類(lèi)型 | 說(shuō)明 |
|---|---|---|---|---|---|
返回狀態(tài)碼 |
return_code |
是 |
SUCCESS |
String(16) |
SUCCESS/FAIL |
返回信息 |
return_msg |
否 |
OK |
String(32) |
返回信息，如非空，為錯(cuò)誤原因 |
商戶(hù)返回示例：
? <return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
</xml>
如果商戶(hù)側(cè)配置了防火墻，需要對(duì)商戶(hù)回調(diào)通知功能開(kāi)通下面白名單網(wǎng)段：
101.226.233.128/25