固定臺牌碼支付
1. 產(chǎn)品介紹
1.1 簡介
匯付提供聚合臺牌碼，支持支付寶、微信、銀聯(lián)二維碼支付（云閃付）等支付方式，消費者通過微信/支付寶/云閃付/瀏覽器/第三方APP等掃描臺牌碼，輸入訂單金額進行支付。
1.2 應(yīng)用場景
適用對象：開通微信、支付寶、銀聯(lián)二維碼支付（云閃付）權(quán)限的商戶；
匯付支持：
- 手續(xù)費配置（內(nèi)扣、外扣、實收、后收、線上、線下）；
- 支持間連和直連掃碼類型、支持指定子賬戶入金、支持ATU代金券;
臺牌碼支付示例：
流程圖：
2. 接入前準(zhǔn)備
2.1 商務(wù)準(zhǔn)備
-
選擇接入模式
-
直簽?zāi)Ｊ剑褐干虘襞c匯付直接簽約。具體流程：商戶完成協(xié)議簽署后，將準(zhǔn)備好的入網(wǎng)材料提供給匯付銷售人員，由匯付銷售人員發(fā)起商戶入網(wǎng)申請，待審核通過入網(wǎng)成功后，商戶聯(lián)系人將收到短信通知控臺賬號及密碼。
-
服務(wù)商模式：指服務(wù)商與匯付簽約，服務(wù)商通過接口或控臺方式完成商戶入網(wǎng)。具體流程：服務(wù)商完成協(xié)議簽署后，將準(zhǔn)備好的入網(wǎng)材料提供給匯付銷售人員，由匯付銷售人員發(fā)起服務(wù)商入網(wǎng)申請，待審核通過入網(wǎng)成功后，服務(wù)商聯(lián)系人將收到短信通知控臺賬號及密碼。
-
在斗拱完成商戶進件入網(wǎng)
- 直簽?zāi)Ｊ剑阂延袇R付銷售人員申請開通，商戶無須另行操作；
- 服務(wù)商模式：
- 控臺入網(wǎng)：參考服務(wù)商控臺進件流程，渠道商接入指引；
- API入網(wǎng)：企業(yè)商戶調(diào)用企業(yè)商戶基本信息入駐接口 、小微商戶調(diào)用個人商戶基本信息入駐接口 完成開戶、綁卡、結(jié)算配置。
2.2 對接準(zhǔn)備
第一步：密鑰獲取
聯(lián)調(diào)之前需要先獲取公私鑰，參見公私解鑰參數(shù)獲取說明；
第二步：公共參數(shù)獲取
登錄服務(wù)商/商戶控臺后，可在開發(fā)設(shè)置-開發(fā)者信息中，獲取sys_id，product_id參數(shù)信息;
第三步：業(yè)務(wù)開通及配置
- 服務(wù)商模式：
步驟一：服務(wù)商功能及權(quán)限開通。服務(wù)商通過線下簽約方式申請支付寶支付、微信支付、銀聯(lián)二維碼支付功能，匯付運營人員在審核好服務(wù)商資料之后，為服務(wù)商開通相關(guān)支付功能，及費率配置。
步驟二：為商戶開通功能及權(quán)限。服務(wù)商權(quán)限及費率配置完成后，服務(wù)商可在服務(wù)商控臺為下屬商戶申請開通相關(guān)支付功能，或通過調(diào)用 商戶業(yè)務(wù)開通 接口開通。具體流程請參考API文檔，商戶進件。
- 直簽商戶：
與客戶經(jīng)理確認(rèn)已開通功能及相關(guān)費率及APPID配置。
- 生成臺牌碼：
在【終端管理】-》【終端查詢】-》【新增商戶二維碼】功能下為商戶生成二維碼；
- 下載打印二維碼
渠道商可以在渠道商控臺配置、下載臺牌碼；
商戶也可以在商戶控臺自行下載二維碼。
3. 開發(fā)指引
3.1 對接規(guī)范
調(diào)用匯付接口，均采取POST形式提交，數(shù)據(jù)格式統(tǒng)一為JSON格式，相關(guān)SDK及簽名方法見鏈接：
SDK示例：Java SDK
加簽驗簽：v2版接口加簽驗簽
3.2 確認(rèn)業(yè)務(wù)配置
- 商戶業(yè)務(wù)已開通、費率已配置；（如已與客戶經(jīng)理確認(rèn)，該步驟可忽略）
查詢方式
1）服務(wù)商控臺：【商戶信息】【查看】【商戶變更】【業(yè)務(wù)信息】【基礎(chǔ)支付】
2）商戶控臺：【我的信息】
3）通過商戶詳細(xì)信息查詢接口來確認(rèn)相關(guān)配置。
- 商戶實名認(rèn)證狀態(tài)已完成，實名認(rèn)證狀態(tài)顯示已授權(quán)。
查詢方式
1）服務(wù)商控臺：【商戶信息】
2）通過微信實名認(rèn)證狀態(tài)查詢/支付寶實名認(rèn)證查詢接口來確認(rèn)相關(guān)配置。
3.3 系統(tǒng)調(diào)用流程
3.3.1 交易流程
無需調(diào)用接口；
3.3.2 退款流程
完整的交易流程還要包括退款。由于用戶或者商戶的原因需要退款時，商戶可以通過本接口將支付款退還給用戶，退款成功資金將原路返回。參見掃碼交易退款接口；
關(guān)注以下請參：
| 參數(shù) | 中文名 | 必填 | 說明 |
|---|---|---|---|
| org_req_date | 原交易請求日期 | Y | 用戶發(fā)起支付的日期 |
| org_req_seq_id | 原交易請求流水號 | C | 商戶系統(tǒng)發(fā)給斗拱的指令流水號 |
| org_hf_seq_id | 原交易全局流水號 | C | 匯付生成的系統(tǒng)流水號 |
| org_party_order_id | 原交易微信支付寶的商戶單號 | C | 該筆交易在微信端的流水號 |
| ord_amt | 申請退款金額 | Y | 退款金額<=原交易金額 |
-
原交易請求流水號、原交易全局流水號、原交易微信支付寶的商戶單號三選一即可；
-
退款金額不能大于交易金額；由于接口支持多次部分退款，多次退款場景下退款總額不能高于原交易金額；
-
退款也是以異步返回的成功或失敗狀態(tài)為最終結(jié)果；
-
一些特殊場景下退款時效可能比較長，注意接口描述文檔中的退款時效說明；
-
商戶控臺也可以支持退款操作，無需聯(lián)調(diào)接口；
點擊【詳情】查看交易詳情，在詳情頁面操作退款；
3.3.3 對賬流程
為了滿足商戶財務(wù)的對賬需求，斗拱提供了對賬功能。
方案一：控臺下載；
方案二：接口獲取；參見交易結(jié)算對賬單查詢接口
- 接口下載的對賬文件包括以下四類：
- 日對賬單類型：包括日結(jié)算對賬單、日分賬對賬單、日出金對賬單；
- 日交易數(shù)據(jù)：主要是各種支付交易記錄；
- 月結(jié)算對賬單：按月匯總的結(jié)算對賬單；
- 月交易數(shù)據(jù)：按月匯總支付交易記錄；
3.3.4 異步通知
針對交易結(jié)果，匯付會通過異步消息的方式通知客戶系統(tǒng)。
調(diào)用匯付接口時上送的異步通知地址為http/https路徑：服務(wù)器為POST回調(diào)，默認(rèn)超時時間為5秒，超時后會重試3次；不支持HTTP重定向；服務(wù)器對應(yīng)答不是200~300之間的錯誤，會默認(rèn)重試3次；異步通知服務(wù)器對HTTPS不認(rèn)證驗簽和ALLOW_ALL_HOSTNAME_VERIFIER；如商戶自定義通知端口，請使用8000-9005內(nèi)端口，否則無法通知；URL 上請勿附帶參數(shù)；異步回調(diào)請求編碼集為：UTF-8；收到通知后請返回狀態(tài)碼“200”,響應(yīng)異步通知。
注意事項：
同樣的異步消息可能會通知多次，因此接收異步消息的處理需做好冪等，保障多次接收到同樣的消息處理后結(jié)果不變。
在實現(xiàn)異步消息接收的同時，都建議您在重要的業(yè)務(wù)環(huán)節(jié)，通過反查接口確認(rèn) 非終態(tài) 支付訂單的狀態(tài)，以保證在發(fā)生異步消息延遲或無法送達(dá)情況下的支付結(jié)果一致性。
詳見異步通知使用說明。
4. API列表
| 類型 | 功能 | 描述 |
|---|---|---|
| API | 交易查詢 | 查詢支付交易信息 |
| API | 交易退款 | 申請退款 |
| API | 交易退款查詢 | 查詢退款進度及結(jié)果 |
| API | 交易關(guān)單 | 長時間未支付做關(guān)單處理 |
| API | 交易關(guān)單查詢 | 交易關(guān)單查詢 |
| API | 微信用戶標(biāo)識查詢 | 輔助類接口,微信用戶標(biāo)識查詢 |
5.常見問題
- 微信支付時，接口報錯："sub_mch_id與sub_appid不匹配"
問題原因：微信公眾號/小程序支付時報此錯誤，一般是商戶未正確配置交易所使用的微信公眾號/小程序 appid 到微信側(cè)。
解決方案：
1） 渠道商控臺給商戶配置，如下圖：
2） 通過接口配置：
微信商戶配置 https://paas.huifu.com/partners/api/#/shgl/shjj/api_shjj_wxshpz
- 微信支付時，接口報錯:”當(dāng)前商戶需補齊相關(guān)資料后，才可進行相應(yīng)的支付交易，請商戶聯(lián)系對接的微信支付服務(wù)商 ”
問題原因：此錯誤一般是商戶還沒有完成微信實名認(rèn)證。
解決方案：完成微信實名認(rèn)證
1).渠道商控臺進行實名認(rèn)證，菜單如圖：
2).掃拓展碼進行實名驗證（可聯(lián)系匯付人員指導(dǎo)）
3).通過接口進行實名認(rèn)證：
實名認(rèn)證接口：https://paas.huifu.com/partners/api/#/shgl/shjj/api_shjj_wxsmrz
- 微信支付返回：redirect_uri域名與后臺配置不一致
問題原因：網(wǎng)頁授權(quán)頁面未正確配置。
解決方案：登錄服務(wù)商微信后臺配置下網(wǎng)頁授權(quán)域名。
微信后臺 在 設(shè)置與開發(fā) -> 公眾號設(shè)置 -> 功能設(shè)置 中找到 網(wǎng)頁授權(quán)域名
- 支付接口調(diào)用報錯：“resp_desc”：“數(shù)據(jù)權(quán)限認(rèn)證失敗”
問題原因：商戶信息校驗沒有通過。
解決方案：
1）檢查報文中的產(chǎn)品號（product_id）是否填寫正確;
2）檢查報文中的系統(tǒng)號（sys_id）和商戶號（huifu_Id） 從屬關(guān)系是否正確。
- 為什么交易成功以后會收到 2 條異步通知？
2條異步通知分別是 交易異步 跟 賬務(wù)異步，用 notify_type 字段區(qū)分。
1). 交易異步情況
notify_type='1'，trans_stat='F' 時，不推送賬務(wù)異步
notify_type='1'，trans_stat='S' 時，會推送賬務(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)排查）
更多問題詳見斗拱開發(fā)者社區(qū)：https://service.dougong.net/t/qa
