微信小程序支付

最近更新時(shí)間：2023.7.25

1. 產(chǎn)品介紹

1.1 簡(jiǎn)介

微信小程序：商戶自行申請(qǐng)的微信小程序，進(jìn)行商品信息和訂單管理，在用戶確認(rèn)商戶訂單信息后調(diào)用微信支付完成下單購(gòu)買的流程。

1.2 應(yīng)用場(chǎng)景

適用對(duì)象：開通了微信線上、線下小程序支付權(quán)限的商戶；

匯付支持：

1. 小程序支付開通、小程序支付配置（小程序參數(shù)）、小程序支付（AT）、AT活動(dòng)報(bào)名、手續(xù)費(fèi)配置（內(nèi)扣、外扣、實(shí)收、后收、線上、線下）；
2. 支持AT代金券、支持AT商家券;

微信小程序支付示例：

流程圖：

2. 接入前準(zhǔn)備

2.1 商務(wù)準(zhǔn)備

1. 選擇接入模式

2. 直簽?zāi)Ｊ剑褐干虘襞c匯付直接簽約。具體流程：商戶完成協(xié)議簽署后，將準(zhǔn)備好的入網(wǎng)材料提供給匯付銷售人員，由匯付銷售人員發(fā)起商戶入網(wǎng)申請(qǐng)，待審核通過(guò)入網(wǎng)成功后，商戶聯(lián)系人將收到短信通知控臺(tái)賬號(hào)及密碼。

3. 服務(wù)商模式：指服務(wù)商與匯付簽約，服務(wù)商通過(guò)接口或控臺(tái)方式完成商戶入網(wǎng)。具體流程：服務(wù)商完成協(xié)議簽署后，將準(zhǔn)備好的入網(wǎng)材料提供給匯付銷售人員，由匯付銷售人員發(fā)起服務(wù)商入網(wǎng)申請(qǐng)，待審核通過(guò)入網(wǎng)成功后，服務(wù)商聯(lián)系人將收到短信通知控臺(tái)賬號(hào)及密碼。

4. 在斗拱完成商戶進(jìn)件入網(wǎng)

   1. 直簽?zāi)Ｊ剑阂延袇R付銷售人員申請(qǐng)開通，商戶無(wú)須另行操作；
   2. 服務(wù)商模式：
      1. 控臺(tái)入網(wǎng)：參考服務(wù)商控臺(tái)進(jìn)件流程，渠道商接入指引；
      2. API入網(wǎng)：企業(yè)商戶調(diào)用企業(yè)商戶基本信息入駐接口 、小微商戶調(diào)用個(gè)人商戶基本信息入駐接口 完成開戶、綁卡、結(jié)算配置。

5. 選擇接入功能并準(zhǔn)備相關(guān)材料

   1. 微信支付：提供商戶或服務(wù)商主體的小程序APPID;

2.2 對(duì)接準(zhǔn)備

第一步：密鑰獲取

聯(lián)調(diào)之前需要先獲取公私鑰，參見(jiàn)公私解鑰參數(shù)獲取說(shuō)明；

第二步：公共參數(shù)獲取

登錄服務(wù)商/商戶控臺(tái)后，可在開發(fā)設(shè)置-開發(fā)者信息中，獲取sys_id，product_id參數(shù)信息;

第三步：業(yè)務(wù)開通及配置

• 服務(wù)商模式：

步驟一：服務(wù)商功能及權(quán)限開通。服務(wù)商通過(guò)線下簽約方式申請(qǐng)微信功能，匯付運(yùn)營(yíng)人員在審核好服務(wù)商資料之后，為服務(wù)商開通相關(guān)支付功能，及費(fèi)率配置。

步驟二：為商戶開通功能及權(quán)限。服務(wù)商權(quán)限及費(fèi)率配置完成后，服務(wù)商可在服務(wù)商控臺(tái)為下屬商戶申請(qǐng)開通相關(guān)支付功能，或通過(guò)調(diào)用 商戶業(yè)務(wù)開通 接口開通。具體流程請(qǐng)參考API文檔，商戶進(jìn)件。

•  直簽商戶：

與客戶經(jīng)理確認(rèn)已開通功能及相關(guān)費(fèi)率及APPID配置。

3. 開發(fā)指引

3.1 對(duì)接規(guī)范

調(diào)用匯付接口，均采取POST形式提交，數(shù)據(jù)格式統(tǒng)一為JSON格式，相關(guān)SDK及簽名方法見(jiàn)鏈接：

SDK示例：Java SDK

加簽驗(yàn)簽：v2版接口加簽驗(yàn)簽

3.2 確認(rèn)業(yè)務(wù)配置

3.2.1 微信側(cè)準(zhǔn)備：

1. 商戶在微信公眾平臺(tái)有賬號(hào)而且有小程序，開發(fā)階段可以使用體驗(yàn)版本進(jìn)行測(cè)試，需要將小程序先上線，小程序上線需通過(guò)微信審核。

3.2.2 斗拱側(cè)準(zhǔn)備:

1. 商戶微信小程序業(yè)務(wù)已開通、小程序appid已配置、小程序費(fèi)率已配置；（如已與客戶經(jīng)理確認(rèn)，該步驟可忽略）

查詢方式

1）服務(wù)商控臺(tái)：【商戶信息】【查看】【商戶變更】【業(yè)務(wù)信息】【基礎(chǔ)支付】

2）商戶控臺(tái)：【我的信息】

3）通過(guò)微信配置查詢接口來(lái)確認(rèn)相關(guān)配置。

2. 商戶微信實(shí)名認(rèn)證狀態(tài)已完成，實(shí)名認(rèn)證狀態(tài)顯示已授權(quán)（微信側(cè)實(shí)際完成即可，斗拱控臺(tái)可能存在狀態(tài)更新不及時(shí)）。

查詢方式

1）服務(wù)商控臺(tái)：【商戶信息】

2）通過(guò)微信實(shí)名認(rèn)證狀態(tài)查詢接口來(lái)確認(rèn)相關(guān)配置。

3.3 系統(tǒng)調(diào)用流程

3.3.1 交易流程

接入步驟說(shuō)明：

1. 通過(guò)授權(quán)獲取用戶 open_id a.小程序端調(diào)用 wx.login(Object object)接口 獲取登錄憑證（code）示例：

wx.login({
    success (res) {
        if (res.code) {
            //發(fā)起網(wǎng)絡(luò)請(qǐng)求
            wx.request({
                url: 'https://test.com/onLogin',
                data: {
                code: res.code
                }
            })
        } else {
            console.log('登錄失敗！' + res.errMsg)
        }
    }
})復(fù)制代碼復(fù)制失敗復(fù)制成功

b. 商戶服務(wù)端使用第一步獲取的code 換取 open_id ，后臺(tái)調(diào)用接口 獲取openID 示例代碼如下：

/*GET https://api.weixin.qq.com/sns/jscode2session?appid=APPID&secret=SECRET&js_code=JSCODE&grant_type=authorization_code*/

url = 'https://api.weixin.qq.com/sns/jscode2session'
params = {
        'appid': app_id,
        'secret': 'wx_secret',
        'js_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')復(fù)制代碼復(fù)制失敗復(fù)制成功

2. 商戶服務(wù)端使用 open_id 下單

調(diào)用 聚合正掃 接口下單拉起支付，需要傳入前端調(diào)用獲得的 open_id 獲取微信返回支付 pay_info信息。

聚合正掃接口需關(guān)注以下字段：

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

同步返回關(guān)注以下字段：

3. 小程序端發(fā)起支付

小程序端使用聚合正掃返回的pay_info 調(diào)用wx.requestPayment(OBJECT)發(fā)起微信支付。

    wx.requestPayment(
    {
        'timeStamp': '',
        'nonceStr': '',
        'package': '',
        'signType': 'MD5',
        'paySign': '',
        'success':function(res){},
        'fail':function(res){},
        'complete':function(res){}
    })復(fù)制代碼復(fù)制失敗復(fù)制成功

4. 交易終態(tài)獲取

客戶支付完成后匯付會(huì)將支付結(jié)果推送到客戶異步地址，主要關(guān)注參數(shù)如下

如果長(zhǎng)時(shí)間未收到異步結(jié)果可以調(diào)用掃碼交易查詢接口查詢交易狀態(tài)；

3.3.2 退款流程

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

關(guān)注以下請(qǐng)參：

• 原交易請(qǐng)求流水號(hào)、原交易全局流水號(hào)、原交易微信支付寶的商戶單號(hào)三選一即可；
• 退款金額不能大于交易金額；由于接口支持多次部分退款，多次退款場(chǎng)景下退款總額不能高于原交易金額；
• 退款也是以異步返回的成功或失敗狀態(tài)為最終結(jié)果；
• 一些特殊場(chǎng)景下退款時(shí)效可能比較長(zhǎng)，注意接口描述文檔中的退款時(shí)效說(shuō)明；

3.3.3 對(duì)賬流程

為了滿足商戶財(cái)務(wù)的對(duì)賬需求，斗拱提供了對(duì)賬功能。

方案一：控臺(tái)下載；

方案二：接口獲取；參見(jiàn)交易結(jié)算對(duì)賬單查詢接口

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

3.3.4 異步通知

針對(duì)交易結(jié)果，匯付會(huì)通過(guò)異步消息的方式通知客戶系統(tǒng)。 

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

注意事項(xiàng)：

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

在實(shí)現(xiàn)異步消息接收的同時(shí)，都建議您在重要的業(yè)務(wù)環(huán)節(jié)，通過(guò)反查接口確認(rèn) 非終態(tài) 支付訂單的狀態(tài)，以保證在發(fā)生異步消息延遲或無(wú)法送達(dá)情況下的支付結(jié)果一致性。

詳見(jiàn)異步通知使用說(shuō)明。

4. API列表

5.常見(jiàn)問(wèn)題

1. 微信支付時(shí)，接口報(bào)錯(cuò)："sub_mch_id與sub_appid不匹配"

問(wèn)題原因：微信公眾號(hào)/小程序支付時(shí)報(bào)此錯(cuò)誤，一般是商戶未正確配置交易所使用的微信公眾號(hào)/小程序 appid 到微信側(cè)。

解決方案：

     1） 渠道商控臺(tái)給商戶配置，如下圖：

      2） 通過(guò)接口配置： 

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

2. 微信支付時(shí)，接口報(bào)錯(cuò):”當(dāng)前商戶需補(bǔ)齊相關(guān)資料后，才可進(jìn)行相應(yīng)的支付交易，請(qǐng)商戶聯(lián)系對(duì)接的微信支付服務(wù)商 ”

問(wèn)題原因：此錯(cuò)誤一般是商戶還沒(méi)有完成微信實(shí)名認(rèn)證。

解決方案：完成微信實(shí)名認(rèn)證

1).渠道商控臺(tái)進(jìn)行實(shí)名認(rèn)證，菜單如圖：

2).掃拓展碼進(jìn)行實(shí)名驗(yàn)證（可聯(lián)系匯付人員指導(dǎo)）

3).通過(guò)接口進(jìn)行實(shí)名認(rèn)證：

實(shí)名認(rèn)證接口：https://paas.huifu.com/partners/api/#/shgl/shjj/api_shjj_wxsmrz

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

問(wèn)題原因：網(wǎng)頁(yè)授權(quán)頁(yè)面未正確配置。

解決方案：登錄服務(wù)商微信后臺(tái)配置下網(wǎng)頁(yè)授權(quán)域名。

微信后臺(tái) 在 設(shè)置與開發(fā) -> 公眾號(hào)設(shè)置 -> 功能設(shè)置 中找到 網(wǎng)頁(yè)授權(quán)域名

4. 支付接口調(diào)用報(bào)錯(cuò)：“resp_desc”：“數(shù)據(jù)權(quán)限認(rèn)證失敗”

問(wèn)題原因：商戶信息校驗(yàn)沒(méi)有通過(guò)。

解決方案：

1）檢查報(bào)文中的產(chǎn)品號(hào)（product_id）是否填寫正確;

2）檢查報(bào)文中的系統(tǒng)號(hào)（sys_id）和商戶號(hào)（huifu_Id） 從屬關(guān)系是否正確。

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

2條異步通知分別是 交易異步 跟 賬務(wù)異步，用 notify_type 字段區(qū)分。

1). 交易異步情況

notify_type='1'，trans_stat='F' 時(shí)，不推送賬務(wù)異步

notify_type='1'，trans_stat='S' 時(shí)，會(huì)推送賬務(wù)異步

2). 賬務(wù)異步情況：

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

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

更多問(wèn)題詳見(jiàn)斗拱開發(fā)者社區(qū)：https://service.dougong.net/t/qa