1. 產品介紹

1.1 簡介

消費者在PC端網(wǎng)頁瀏覽，確認訂單后，網(wǎng)頁上生成銀聯(lián)付費二維碼，供消費者掃碼支付。支持銀聯(lián)云閃付APP以及集成云閃付或接入云閃付的APP，包括但不限于工行、中行、招行等銀行類APP，以及京東等一些第三方APP。

1.2 應用場景

適用對象：開通銀聯(lián)二維碼支付權限的商戶；

匯付支持：

1. 手續(xù)費配置（內扣、外扣、實收、后收、線上、線下）；
2. 支持間連和直連掃碼類型、支持指定子賬戶入金、支持ATU代金券;（ATU指支付寶/微信/銀聯(lián)，下同。更多名詞解釋，請參考名詞解釋。）

PC二維碼支付示例：

客戶選擇商品后，提交訂單，進入收銀臺，提供微信、支付寶、銀聯(lián)支付、數(shù)字人民幣等支付方式。

可以通過斗拱收款演示網(wǎng)站了解銀聯(lián)支付掃碼付款的效果；

流程圖：

2. 接入前準備

2.1 商務準備

1. 選擇接入模式

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

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

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

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

2.2 對接準備

第一步：密鑰獲取

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

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

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

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

• 服務商模式：

步驟一：服務商功能及權限開通。服務商通過線下簽約方式申請支付寶支付、微信支付、銀聯(lián)二維碼支付、數(shù)字貨幣功能，匯付運營人員在審核好服務商資料之后，為服務商開通相關支付功能，及費率配置。

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

•  直簽商戶：

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

3. 開發(fā)指引

3.1 對接規(guī)范

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

SDK示例：Java SDK

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

3.2 確認業(yè)務配置

1. 商戶業(yè)務已開通、費率已配置；（如已與客戶經理確認，該步驟可忽略）

查詢方式

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

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

3）通過商戶詳細信息查詢接口來確認相關配置。

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

3.3.1 交易流程

1. 商戶服務器端調用 聚合正掃 接口下單拉起支付，trade_type: U_JSAPI(銀聯(lián)JS)。
2. 拿到服務端返回的payinfo信息中的qr_code，在pc站點上轉成二維碼展示；
3. 用戶掃碼支付；
4. 獲取終態(tài)，客戶支付完成后匯付會將支付結果推送到客戶異步地址，如果長時間未收到異步結果可以調用掃碼交易查詢接口查詢交易狀態(tài)；

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

同步返回關注以下字段：

交易終態(tài)獲取

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

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

3.3.2 退款流程

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

關注以下請參：

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

3.3.3 對賬流程

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

方案一：控臺下載；

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

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

3.3.4 異步通知

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

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

注意事項：

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

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

詳見異步通知使用說明。

4. API列表

5.常見問題

1. 支付接口調用報錯：“resp_desc”：“數(shù)據(jù)權限認證失敗”

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

解決方案：

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

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

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

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

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' 表示交易成功-入賬失敗（非正常情況，可聯(lián)系匯付技術人員確認排查）

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