固定臺牌碼支付
1. 產品介紹
1.1 簡介
匯付提供聚合臺牌碼，支持支付寶、微信、銀聯二維碼支付（云閃付）等支付方式，消費者通過微信/支付寶/云閃付/瀏覽器/第三方APP等掃描臺牌碼，輸入訂單金額進行支付。
1.2 應用場景
適用對象：開通微信、支付寶、銀聯二維碼支付（云閃付）權限的商戶；
匯付支持：
- 手續費配置（內扣、外扣、實收、后收、線上、線下）；
- 支持間連和直連掃碼類型、支持指定子賬戶入金、支持ATU代金券;
臺牌碼支付示例：
流程圖：
2. 接入前準備
2.1 商務準備
-
選擇接入模式
-
直簽模式：指商戶與匯付直接簽約。具體流程：商戶完成協議簽署后，將準備好的入網材料提供給匯付銷售人員，由匯付銷售人員發起商戶入網申請，待審核通過入網成功后，商戶聯系人將收到短信通知控臺賬號及密碼。
-
服務商模式：指服務商與匯付簽約，服務商通過接口或控臺方式完成商戶入網。具體流程：服務商完成協議簽署后，將準備好的入網材料提供給匯付銷售人員，由匯付銷售人員發起服務商入網申請，待審核通過入網成功后，服務商聯系人將收到短信通知控臺賬號及密碼。
-
在斗拱完成商戶進件入網
- 直簽模式：已有匯付銷售人員申請開通，商戶無須另行操作；
- 服務商模式：
- 控臺入網：參考服務商控臺進件流程，渠道商接入指引；
- API入網：企業商戶調用企業商戶基本信息入駐接口 、小微商戶調用個人商戶基本信息入駐接口 完成開戶、綁卡、結算配置。
2.2 對接準備
第一步：密鑰獲取
聯調之前需要先獲取公私鑰，參見公私解鑰參數獲取說明；
第二步：公共參數獲取
登錄服務商/商戶控臺后，可在開發設置-開發者信息中，獲取sys_id，product_id參數信息;
第三步：業務開通及配置
- 服務商模式：
步驟一：服務商功能及權限開通。服務商通過線下簽約方式申請支付寶支付、微信支付、銀聯二維碼支付功能，匯付運營人員在審核好服務商資料之后，為服務商開通相關支付功能，及費率配置。
步驟二：為商戶開通功能及權限。服務商權限及費率配置完成后，服務商可在服務商控臺為下屬商戶申請開通相關支付功能，或通過調用 商戶業務開通 接口開通。具體流程請參考API文檔，商戶進件。
- 直簽商戶：
與客戶經理確認已開通功能及相關費率及APPID配置。
- 生成臺牌碼：
在【終端管理】-》【終端查詢】-》【新增商戶二維碼】功能下為商戶生成二維碼；
- 下載打印二維碼
渠道商可以在渠道商控臺配置、下載臺牌碼；
商戶也可以在商戶控臺自行下載二維碼。
3. 開發指引
3.1 對接規范
調用匯付接口，均采取POST形式提交，數據格式統一為JSON格式，相關SDK及簽名方法見鏈接：
SDK示例：Java SDK
加簽驗簽：v2版接口加簽驗簽
3.2 確認業務配置
- 商戶業務已開通、費率已配置；（如已與客戶經理確認，該步驟可忽略）
查詢方式
1）服務商控臺：【商戶信息】【查看】【商戶變更】【業務信息】【基礎支付】
2）商戶控臺：【我的信息】
3）通過商戶詳細信息查詢接口來確認相關配置。
- 商戶實名認證狀態已完成，實名認證狀態顯示已授權。
查詢方式
1）服務商控臺：【商戶信息】
2）通過微信實名認證狀態查詢/支付寶實名認證查詢接口來確認相關配置。
3.3 系統調用流程
3.3.1 交易流程
無需調用接口；
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 對賬流程
為了滿足商戶財務的對賬需求，斗拱提供了對賬功能。
方案一：控臺下載；
方案二：接口獲?。粎⒁?a target="_blank" rel="noopener">交易結算對賬單查詢接口
- 接口下載的對賬文件包括以下四類：
- 日對賬單類型：包括日結算對賬單、日分賬對賬單、日出金對賬單；
- 日交易數據：主要是各種支付交易記錄；
- 月結算對賬單：按月匯總的結算對賬單；
- 月交易數據：按月匯總支付交易記錄；
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 | 交易查詢 | 查詢支付交易信息 |
| 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' 表示交易成功-入賬失?。ǚ钦Ｇ闆r，可聯系匯付技術人員確認排查）
更多問題詳見斗拱開發者社區：https://service.dougong.net/t/qa
