產品介紹

微信公眾號：商戶自行申請的微信公眾號，進行商品信息和訂單管理，在用戶確認商戶訂單信息后調用微信支付完成下單購買的流程。

1.2 應用場景

適用對象：開通了微信線上、線下公眾號支付權限的商戶；

匯付支持：

1. 公眾號支付開通、公眾號支付配置、手續費配置（內扣、外扣、實收、后收、線上、線下）；
2. 支持AT代金券、支持AT商家券;（AT指支付寶與微信，下同。更多名詞解釋，請參考名詞解釋。）

微信公眾號支付示例：

流程圖：

可以通過斗拱收款演示網站了解微信公眾號支付在PC端的應用效果;

2. 接入前準備

2.1 商務準備

1. 客戶首先要有微信公眾號

2. 選擇接入模式

3. 直簽模式：指商戶與匯付直接簽約。具體流程：商戶完成協議簽署后，將準備好的入網材料提供給匯付銷售人員，由匯付銷售人員發起商戶入網申請，待審核通過入網成功后，商戶聯系人將收到短信通知控臺賬號及密碼。

4. 服務商模式：指服務商與匯付簽約，服務商通過接口或控臺方式完成商戶入網。具體流程：服務商完成協議簽署后，將準備好的入網材料提供給匯付銷售人員，由匯付銷售人員發起服務商入網申請，待審核通過入網成功后，服務商聯系人將收到短信通知控臺賬號及密碼。

5. 在斗拱完成商戶進件入網

   1. 直簽模式：已有匯付銷售人員申請開通，商戶無須另行操作；
   2. 服務商模式：
      1. 控臺入網：參考服務商控臺進件流程，渠道商接入指引；
      2. API入網：企業商戶調用 企業商戶基本信息入駐接口 、小微商戶調用 個人商戶基本信息入駐接口 完成開戶、綁卡、結算配置。

6. 選擇接入功能并準備相關材料

   1. 微信支付：提供商戶或服務商主體的公眾號 APPID；

2.2 對接準備

第一步：密鑰獲取

聯調之前需要先獲取公私鑰，參見公私解鑰參數獲取說明；

第二步：公共參數獲取

登錄服務商/商戶控臺后，可在開發設置-開發者信息中，獲取sys_id，product_id參數信息；

第三步：業務開通及配置

• 服務商模式：

步驟一：服務商功能及權限開通。服務商通過線下簽約方式申請微信功能，匯付運營人員在審核好服務商資料之后，為服務商開通相關支付功能，及費率配置。

步驟二：為商戶開通功能及權限。服務商權限及費率配置完成后，服務商可在服務商控臺為下屬商戶申請開通相關支付功能，或通過調用商戶業務開通接口開通。具體流程請參考商戶進件說明。

• 直簽商戶：

與客戶經理確認已開通功能及相關費率及APPID配置。

3. 開發指引

3.1 對接規范

調用匯付接口，均采取POST形式提交，數據格式統一為JSON格式，相關SDK及簽名方法見鏈接：

SDK示例：JavaSDK開發工具包

加簽驗簽：v2版接口加簽驗簽

3.2 確認業務配置

1. 商戶微信公眾號業務已開通、appid已配置、費率已配置;（如已與客戶經理確認，該步驟可忽略）

查詢方式

1）服務商控臺：【商戶信息】【查看】【商戶變更】【業務信息】【基礎支付】

2）商戶控臺：【我的信息】

3）通過微信配置查詢接口來確認相關配置。

2. 商戶微信實名認證狀態已完成，實名認證狀態顯示已授權（微信側實際完成即可，斗拱控臺可能存在狀態更新不及時）。

查詢方式

1）服務商控臺：【商戶信息】

2）通過微信實名認證狀態查詢接口來確認相關配置。

3.3 系統調用流程

交易流程

主要有以下幾個步驟：

• 生成一個自定義的微信收銀頁面(如下圖)，在PC上展示頁面地址的二維碼圖片；
  

• 用戶用微信掃碼后點擊"支付"，后面的調用流程與H5頁面的微信公眾號支付流程相同；

• 通過授權獲取用戶 open_id

• 用前端獲取的用戶信息調斗拱聚合正掃接口；

• 聚合正掃接口返回的pay_info提供前端頁面發起支付;

• 斗拱會將交易結果通知到商戶后端系統。

接入步驟詳細說明：

1. 通過授權獲取用戶 open_id

? 授權說明見微信官方鏈接： 網頁授權

• 微信公眾號后臺配置授權域名，將微信校驗文件放到服務器根目錄下
• 用戶靜默授權獲取code，前端頁面在微信內打開授權地址，成功后并重定向到自己項目目標地址

只為獲取 open_id的話靜默授權就可以，無需用戶同意。

地址：

/*scope取值：snsapi_base/snsapi_userinfo 
    - snsapi_base （不彈出授權頁面，直接跳轉，只能獲取用戶openid）
    - snsapi_userinfo （彈出授權頁面，可通過openid拿到昵稱、性別、所在地。并且， 即使在未關注的情況下，只要用戶授權，也能獲取其信息 ）
*/
let url=`https://open.weixin.qq.com/connect/oauth2/authorize?appid=${appid}&redirect_uri=${urlNow}&response_type=code&scope=${scope}&state=STATE&connect_redirect=1#wechat_redirect`;
window.location.replace(url);復制代碼復制失敗復制成功

如果用戶同意授權，頁面將跳轉至 redirect_uri/?code=CODE&state=STATE。

• 使用獲取到的code，在服務端調用微信接口獲取 access_token和 open_id

獲取code后，請求以下鏈接獲取access_token：

示例代碼如下：

/*https://api.weixin.qq.com/sns/oauth2/access_token?appid=APPID&secret=SECRET&code=CODE&grant_type=authorization_code*/

url = 'https://api.weixin.qq.com/sns/oauth2/access_token'
params = {
        'appid': app_id,
        'secret': 'wx_secret',
        'code': wx_code,
        'grant_type': 'authorization_code',
}
resp = requests.get(url, params, timeout=15)
result_dict = json.loads(resp.text)
openid=result_dict.get('openid')復制代碼復制失敗復制成功

2. 調用匯付聚合正掃接口

參見 聚合正掃

交易類型 trade_type 選T_JSAPI，用戶子標識 sub_openid 填上一步獲取的openid

將接口應答的支付信息pay_info返回前端頁面

聚合正掃接口需關注以下字段：

參數	中文名	必填	說明
trade_type	交易類型	Y	T_JSAPI: 微信JS支付
time_expire	交易有效期	N	指定交易失效時間，不指定微信默認是2小時，超過有效時間的訂單會默認被關閉
+wx_data	微信拓展參數集合	N	通過前端調服微信獲取的數據換取pay_info;
sub_appid	子商戶公眾賬號ID	N	微信公眾號ID
openid	用戶標識	Y	前端調用微信獲取的用戶在商戶appid下的唯一標識；
sub_openid	子商戶用戶標識	N	前端調用微信獲取的用戶在子商戶appid下的唯一標識；
notify_url	異步通知地址	N	交易異步通知地址，http或https開頭

*其中wx_data中，如填寫openid則無需填寫sub_appid+sub_openid。如不填openid，則需填寫sub_appid和sub_openid。

同步返回關注以下字段：

參數	中文名	說明
trans_stat	交易狀態	同步通常返回“處理中”，交易終態以異步返回為準
resp_desc	業務響應信息	關注失敗原因
bank_message	通道返回描述	關注通道返回的失敗原因
pay_info	支付信息	這個字段后續調用微信需要用到的
hf_seq_id	全局流水號	匯付系統生成全局流水號，后續可以用這個流水號查詢交易

3. 發起支付

前端頁面調用JSAPI 使用聚合正掃返回的pay_info內容發起支付。

示例代碼：

WeixinJSBridge.invoke('getBrandWCPayRequest', {
                "appId": "wx2421b1c4370ec43b",
                "timeStamp": "1395712654",
                "nonceStr": "e61463f8efa94090b1f366cccfbbb444",
                "package": "prepay_id=up_wx21201855730335ac86f8c43d1889123400",
                "signType": "RSA",
                "paySign": "oR9d8PuhnIc+YZ8cBHFCwfgpaK9gd7vaRvkYD7rthRAZ\/X+QBhcCYL21N7cHCTUxbQ+EAt6Uy+lwSN22f5YZvI45MLko8Pfso0jm46v5hqcVwrk6uddkGuT+Cdvu4WBqDzaDjnNa5UK3GfE1Wfl2gHxIIY5lLdUgWFts17D4WuolLLkiFZV+JSHMvH7eaLdT9N5GBovBwu5yYKUR7skR8Fu+LozcSqQixnlEZUfyE55feLOQTUYzLmR9pNtPbPsu6WVhbNHMS3Ss2+AehHvz+n64GDmXxbXIOBvm2olHu3PsOUGRwhudhVf7UcGcunXt8cqNjKNqZLhLw4jq\/xDg==" //微信簽名
        },
        function(res) {
                if (res.err_msg == "get_brand_wcpay_request:ok") {
                        // 使用以上方式判斷前端返回,微信團隊鄭重提示：
                        //res.err_msg將在用戶支付成功后返回ok，但并不保證它絕對可靠。
                }
        });
}
if (typeof WeixinJSBridge == "undefined") {
        if (document.addEventListener) {
                document.addEventListener('WeixinJSBridgeReady', onBridgeReady, false);
        } else if (document.attachEvent) {
                document.attachEvent('WeixinJSBridgeReady', onBridgeReady);
                document.attachEvent('onWeixinJSBridgeReady', onBridgeReady);
        }
} else {
        onBridgeReady();
}復制代碼復制失敗復制成功

注意：

• 間聯模式下JSAPI支付后回到商家頁面的能力微信逐步回收，可利用點金計劃來承載。 參見微信說明。

4. 交易終態獲取

客戶支付完成后匯付會將支付結果推送到客戶異步地址，主要關注參數如下

參數	中文名	說明
settlement_amt	結算金額	用戶實際支付金額。如有優惠該金額小于交易金額；
fee_amount	手續費金額	斗拱扣收的支付手續費金額
trans_stat	交易狀態	交易的最終結果；S：成功、F：失敗
out_trans_id	用戶賬單上的交易訂單號	交易在微信側的流水號，參見用戶賬單說明
party_order_id	用戶賬單上的商戶訂單號	交易在微信側生成的訂單號；參見用戶賬單說明
wx_user_id	微信用戶唯一標識碼	用戶在微信側的ID號
wx_response	微信返回的響應報文	Json格式
bank_message	通道返回描述	如交易失敗可以關注一下通道返回的錯誤描述

如果長時間未收到異步結果可以調用掃碼交易查詢接口查詢交易狀態；

退款流程

完整的交易流程還要包括退款。由于用戶或者商戶的原因需要退款時，商戶可以通過本接口將支付款退還給用戶，退款成功資金將原路返回。參見掃碼交易退款接口；

關注以下請參：

參數	中文名	必填	說明
org_req_date	原交易請求日期	Y	用戶發起支付的日期
org_req_seq_id	原交易請求流水號	C	商戶系統發給斗拱的指令流水號
org_hf_seq_id	原交易全局流水號	C	匯付生成的系統流水號
org_party_order_id	原交易微信的商戶單號	C	該筆交易在微信端的流水號
ord_amt	申請退款金額	Y	退款金額<=原交易金額

• 原交易請求流水號、原交易全局流水號、原交易微信的商戶單號三選一即可；
• 退款金額不能大于交易金額；由于接口支持多次部分退款，多次退款場景下退款總額不能高于原交易金額；
• 退款也是以異步返回的成功或失敗狀態為最終結果；
• 一些特殊場景下退款時效可能比較長，注意接口描述文檔中的退款時效說明；

對賬流程

為了滿足商戶財務的對賬需求，斗拱提供了對賬功能。

方案一：控臺下載；

方案二：接口獲取；參見交易結算對賬單查詢接口

• 接口下載的對賬文件包括以下四類：
  • 日對賬單類型：包括日結算對賬單、日分賬對賬單、日出金對賬單；
  • 日交易數據：主要是各種支付交易記錄；
  • 月結算對賬單：按月匯總的結算對賬單；
  • 月交易數據：按月匯總支付交易記錄；

異步通知

針對交易結果，匯付會通過異步消息的方式通知客戶系統。 

調用匯付接口時上送的異步通知地址為http/https路徑：服務器為POST回調，默認超時時間為5秒，超時后會重試3次；不支持HTTP重定向；服務器對應答不是200~300之間的錯誤，會默認重試3次；異步通知服務器對HTTPS不認證驗簽和ALLOW_ALL_HOSTNAME_VERIFIER；如商戶自定義通知端口，請使用8000-9005內端口，否則無法通知；URL 上請勿附帶參數；異步回調請求編碼集為：UTF-8；收到通知后請返回狀態碼“200”,響應異步通知。

注意事項：

同樣的異步消息可能會通知多次，因此接收異步消息的處理需做好冪等，保障多次接收到同樣的消息處理后結果不變。

在實現異步消息接收的同時，都建議您在重要的業務環節，通過反查接口確認 非終態 支付訂單的狀態，以保證在發生異步消息延遲或無法送達情況下的支付結果一致性。

詳見異步通知使用說明。

4. API列表

類型	功能	描述
API	聚合正掃	商戶服務端調該接口傳入pay_info完成最終交易;
API	交易查詢	查詢支付交易信息
API	交易退款	申請退款
API	交易退款查詢	查詢退款進度及結果
API	交易關單	長時間未支付做關單處理
API	交易關單查詢	交易關單查詢
API	微信用戶標識查詢	輔助類接口,微信用戶標識查詢

5.常見問題

1. 微信支付時，接口報錯："sub_mch_id與sub_appid不匹配"

問題原因：微信公眾號/小程序支付時報此錯誤，一般是商戶未正確配置交易所使用的微信公眾號/小程序 appid 到微信側。

解決方案：

     1） 渠道商控臺給商戶配置，如下圖：

     2） 通過接口配置： 

微信商戶配置 https://paas.huifu.com/partners/api/#/shgl/shjj/api_shjj_wxshpz

2. 微信支付時，接口報錯:”當前商戶需補齊相關資料后，才可進行相應的支付交易，請商戶聯系對接的微信支付服務商 ”

問題原因：此錯誤一般是商戶還沒有完成微信實名認證。

解決方案：完成微信實名認證

1).渠道商控臺進行實名認證，菜單如圖：

2).掃拓展碼進行實名驗證（可聯系匯付人員指導）

3).通過接口進行實名認證：

實名認證接口：https://paas.huifu.com/partners/api/#/shgl/shjj/api_shjj_wxsmrz

3. 微信支付返回：redirect_uri域名與后臺配置不一致

問題原因：網頁授權頁面未正確配置。

解決方案：登錄服務商微信后臺配置下網頁授權域名。

微信后臺 在 設置與開發 -> 公眾號設置 -> 功能設置 中找到 網頁授權域名

4. 支付接口調用報錯：“resp_desc”：“數據權限認證失敗”

問題原因：商戶信息校驗沒有通過。

解決方案：

1）檢查報文中的產品號（product_id）是否填寫正確;

2）檢查報文中的系統號（sys_id）和商戶號（huifu_Id） 從屬關系是否正確。

5. 為什么交易成功以后會收到 2 條異步通知？

2條異步通知分別是 交易異步 跟 賬務異步，用 notify_type 字段區分。

1). 交易異步情況

notify_type='1'，trans_stat='F' 時，不推送賬務異步

notify_type='1'，trans_stat='S' 時，會推送賬務異步

2). 賬務異步情況：

notify_type='2'，trans_stat='S'，acct_stat='S' 表示交易成功-入賬成功

notify_type='2'，trans_stat='S'，acct_stat='F' 表示交易成功-入賬失敗（非正常情況，可聯系匯付技術人員確認排查）

更多問題詳見斗拱開發者社區：https://service.dougong.net/t/qa

由服務使用方的應用程序發起，以Restful風格為主、通過公網HTTP協議調用匯付天下的微信公眾號支付，從而實現程序的自動化交互，提高服務效率。