微信小程序支付
最近更新時間：2023.7.25
1. 產品介紹
1.1 簡介
微信小程序：商戶自行申請的微信小程序，進行商品信息和訂單管理，在用戶確認商戶訂單信息后調用微信支付完成下單購買的流程。
1.2 應用場景
適用對象：開通了微信線上、線下小程序支付權限的商戶；
匯付支持：
- 小程序支付開通、小程序支付配置（小程序參數）、小程序支付（AT）、AT活動報名、手續費配置（內扣、外扣、實收、后收、線上、線下）；
- 支持AT代金券、支持AT商家券;
微信小程序支付示例：
流程圖：
2. 接入前準備
2.1 商務準備
-
選擇接入模式
-
直簽模式：指商戶與匯付直接簽約。具體流程：商戶完成協議簽署后，將準備好的入網材料提供給匯付銷售人員，由匯付銷售人員發起商戶入網申請，待審核通過入網成功后，商戶聯系人將收到短信通知控臺賬號及密碼。
-
服務商模式：指服務商與匯付簽約，服務商通過接口或控臺方式完成商戶入網。具體流程：服務商完成協議簽署后，將準備好的入網材料提供給匯付銷售人員，由匯付銷售人員發起服務商入網申請，待審核通過入網成功后，服務商聯系人將收到短信通知控臺賬號及密碼。
-
在斗拱完成商戶進件入網
- 直簽模式：已有匯付銷售人員申請開通，商戶無須另行操作；
- 服務商模式：
- 控臺入網：參考服務商控臺進件流程，渠道商接入指引；
- API入網：企業商戶調用企業商戶基本信息入駐接口 、小微商戶調用個人商戶基本信息入駐接口 完成開戶、綁卡、結算配置。
-
選擇接入功能并準備相關材料
- 微信支付：提供商戶或服務商主體的小程序APPID;
2.2 對接準備
第一步：密鑰獲取
聯調之前需要先獲取公私鑰，參見公私解鑰參數獲取說明；
第二步：公共參數獲取
登錄服務商/商戶控臺后，可在開發設置-開發者信息中，獲取sys_id，product_id參數信息;
第三步：業務開通及配置
- 服務商模式：
步驟一：服務商功能及權限開通。服務商通過線下簽約方式申請微信功能，匯付運營人員在審核好服務商資料之后，為服務商開通相關支付功能，及費率配置。
步驟二：為商戶開通功能及權限。服務商權限及費率配置完成后，服務商可在服務商控臺為下屬商戶申請開通相關支付功能，或通過調用 商戶業務開通 接口開通。具體流程請參考API文檔，商戶進件。
- 直簽商戶：
與客戶經理確認已開通功能及相關費率及APPID配置。
3. 開發指引
3.1 對接規范
調用匯付接口，均采取POST形式提交，數據格式統一為JSON格式，相關SDK及簽名方法見鏈接：
SDK示例：Java SDK
加簽驗簽：v2版接口加簽驗簽
3.2 確認業務配置
3.2.1 微信側準備：
- 商戶在微信公眾平臺有賬號而且有小程序，開發階段可以使用體驗版本進行測試，需要將小程序先上線，小程序上線需通過微信審核。
3.2.2 斗拱側準備:
- 商戶微信小程序業務已開通、小程序appid已配置、小程序費率已配置；（如已與客戶經理確認，該步驟可忽略）
查詢方式
1）服務商控臺：【商戶信息】【查看】【商戶變更】【業務信息】【基礎支付】
2）商戶控臺：【我的信息】
3）通過微信配置查詢接口來確認相關配置。
- 商戶微信實名認證狀態已完成，實名認證狀態顯示已授權（微信側實際完成即可，斗拱控臺可能存在狀態更新不及時）。
查詢方式
1）服務商控臺：【商戶信息】
2）通過微信實名認證狀態查詢接口來確認相關配置。
3.3 系統調用流程
3.3.1 交易流程
接入步驟說明：
- 通過授權獲取用戶 open_id a.小程序端調用 wx.login(Object object)接口 獲取登錄憑證（code）示例：
wx.login({
success (res) {
if (res.code) {
//發起網絡請求
wx.request({
url: 'https://test.com/onLogin',
data: {
code: res.code
}
})
} else {
console.log('登錄失?。? + res.errMsg)
}
}
})b. 商戶服務端使用第一步獲取的code 換取 open_id ，后臺調用接口 獲取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')- 商戶服務端使用 open_id 下單
調用 聚合正掃 接口下單拉起支付，需要傳入前端調用獲得的 open_id 獲取微信返回支付 pay_info信息。
聚合正掃接口需關注以下字段：
| 參數 | 中文名 | 必填 | 說明 |
|---|---|---|---|
| trade_type | 交易類型 | Y | T_MINIAPP: 微信小程序 |
| time_expire | 交易有效期 | N | 指定交易失效時間，不指定微信默認是2小時，超過有效時間的訂單會默認被關閉 |
| +wx_data | 微信拓展參數集合 | N | 通過前端調服微信獲取的數據換取pay_info; |
| sub_appid | 子商戶公眾賬號ID | N | 微信小程序app_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 | 全局流水號 | 匯付系統生成全局流水號，后續可以用這個流水號查詢交易 |
- 小程序端發起支付
小程序端使用聚合正掃返回的pay_info 調用wx.requestPayment(OBJECT)發起微信支付。
wx.requestPayment(
{
'timeStamp': '',
'nonceStr': '',
'package': '',
'signType': 'MD5',
'paySign': '',
'success':function(res){},
'fail':function(res){},
'complete':function(res){}
})- 交易終態獲取
客戶支付完成后匯付會將支付結果推送到客戶異步地址，主要關注參數如下
| 參數 | 中文名 | 說明 |
|---|---|---|
| settlement_amt | 結算金額 | 用戶實際支付金額。如有優惠該金額小于交易金額； |
| fee_amount | 手續費金額 | 斗拱扣收的支付手續費金額 |
| trans_stat | 交易狀態 | 交易的最終結果；S：成功、F：失敗 |
| out_trans_id | 用戶賬單上的交易訂單號 | 交易在微信側的流水號，參見用戶賬單說明 |
| party_order_id | 用戶賬單上的商戶訂單號 | 交易在微信側生成的訂單號；參見用戶賬單說明 |
| wx_user_id | 微信用戶唯一標識碼 | 用戶在微信側的ID號 |
| wx_response | 微信返回的響應報文 | Json格式 |
| bank_message | 通道返回描述 | 如交易失敗可以關注一下通道返回的錯誤描述 |
如果長時間未收到異步結果可以調用掃碼交易查詢接口查詢交易狀態；
3.3.2 退款流程
完整的交易流程還要包括退款。由于用戶或者商戶的原因需要退款時，商戶可以通過本接口將支付款退還給用戶，退款成功資金將原路返回。參見掃碼交易退款接口；
關注以下請參：
| 參數 | 中文名 | 必填 | 說明 |
|---|---|---|---|
| org_req_date | 原交易請求日期 | Y | 用戶發起支付的日期 |
| org_req_seq_id | 原交易請求流水號 | C | 商戶系統發給斗拱的指令流水號 |
| org_hf_seq_id | 原交易全局流水號 | C | 匯付生成的系統流水號 |
| org_party_order_id | 原交易微信支付寶的商戶單號 | C | 該筆交易在微信端的流水號 |
| ord_amt | 申請退款金額 | Y | 退款金額<=原交易金額 |
- 原交易請求流水號、原交易全局流水號、原交易微信支付寶的商戶單號三選一即可；
- 退款金額不能大于交易金額；由于接口支持多次部分退款，多次退款場景下退款總額不能高于原交易金額；
- 退款也是以異步返回的成功或失敗狀態為最終結果；
- 一些特殊場景下退款時效可能比較長，注意接口描述文檔中的退款時效說明；
3.3.3 對賬流程
為了滿足商戶財務的對賬需求，斗拱提供了對賬功能。
方案一：控臺下載；
方案二：接口獲??；參見交易結算對賬單查詢接口
- 接口下載的對賬文件包括以下四類：
- 日對賬單類型：包括日結算對賬單、日分賬對賬單、日出金對賬單；
- 日交易數據：主要是各種支付交易記錄；
- 月結算對賬單：按月匯總的結算對賬單；
- 月交易數據：按月匯總支付交易記錄；
3.3.4 異步通知
針對交易結果，匯付會通過異步消息的方式通知客戶系統。
調用匯付接口時上送的異步通知地址為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.常見問題
- 微信支付時，接口報錯："sub_mch_id與sub_appid不匹配"
問題原因：微信公眾號/小程序支付時報此錯誤，一般是商戶未正確配置交易所使用的微信公眾號/小程序 appid 到微信側。
解決方案：
1） 渠道商控臺給商戶配置，如下圖：
2） 通過接口配置：
微信商戶配置 https://paas.huifu.com/partners/api/#/shgl/shjj/api_shjj_wxshpz
- 微信支付時，接口報錯:”當前商戶需補齊相關資料后，才可進行相應的支付交易，請商戶聯系對接的微信支付服務商 ”
問題原因：此錯誤一般是商戶還沒有完成微信實名認證。
解決方案：完成微信實名認證
1).渠道商控臺進行實名認證，菜單如圖：
2).掃拓展碼進行實名驗證（可聯系匯付人員指導）
3).通過接口進行實名認證：
實名認證接口：https://paas.huifu.com/partners/api/#/shgl/shjj/api_shjj_wxsmrz
- 微信支付返回：redirect_uri域名與后臺配置不一致
問題原因：網頁授權頁面未正確配置。
解決方案：登錄服務商微信后臺配置下網頁授權域名。
微信后臺 在 設置與開發 -> 公眾號設置 -> 功能設置 中找到 網頁授權域名
- 支付接口調用報錯：“resp_desc”：“數據權限認證失敗”
問題原因：商戶信息校驗沒有通過。
解決方案：
1）檢查報文中的產品號（product_id）是否填寫正確;
2）檢查報文中的系統號（sys_id）和商戶號（huifu_Id） 從屬關系是否正確。
- 為什么交易成功以后會收到 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
