1. 產(chǎn)品介紹

1.1 簡介

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

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

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

匯付支持：

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

PC二維碼支付示例：

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

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

流程圖：

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

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

1. 選擇接入模式

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

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

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

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

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

第一步：密鑰獲取

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

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

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

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

• 服務(wù)商模式：

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

步驟二：為商戶開通功能及權(quán)限。服務(wù)商權(quán)限及費(fèi)率配置完成后，服務(wù)商可在服務(wù)商控臺(tái)為下屬商戶申請(qǐng)開通相關(guān)支付功能，或通過調(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及簽名方法見鏈接：

SDK示例：Java SDK

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

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

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

查詢方式

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

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

3）通過商戶詳細(xì)信息查詢接口來確認(rèn)相關(guān)配置。

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

3.3.1 交易流程

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

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

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

交易終態(tài)獲取

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

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

3.3.2 退款流程

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

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

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

3.3.3 對(duì)賬流程

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

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

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

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

3.3.4 異步通知

針對(duì)交易結(jié)果，匯付會(huì)通過異步消息的方式通知客戶系統(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)端口，否則無法通知；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é)，通過反查接口確認(rèn) 非終態(tài) 支付訂單的狀態(tài)，以保證在發(fā)生異步消息延遲或無法送達(dá)情況下的支付結(jié)果一致性。

詳見異步通知使用說明。

4. API列表

5.常見問題

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

問題原因：商戶信息校驗(yàn)沒有通過。

解決方案：

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' 表示交易成功-入賬失?。ǚ钦Ｇ闆r，可聯(lián)系匯付技術(shù)人員確認(rèn)排查）

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