預授權支付
最近更新時間：2023.7.24
1. 產品介紹
1.1 簡介
預授權指預付款，商戶估算了用戶的消費金額之后，在用戶賬戶、銀行卡內凍結相應的金額，等用戶消費完成后，商戶再進行正式結算，相當于押金。常見的使用場景，如酒店、租賃、醫美等行業。
預授權交易分為 4 個模塊:預授權、預授權撤銷、預授權完成、預授權完成撤銷。
| 交易模塊 | 說明 |
|---|---|
| 預授權 | 預授權交易，僅凍結用戶資金 |
| 預授權撤銷 | 預授權交易撤銷 |
| 預授權完成 | 預授權交易完成 |
| 預授權完成撤銷 | 預授權撤銷交易完成 |
1.2 應用場景
- 匯付提供智能POS機，支持支付寶、微信、銀行卡三種交易方式的預授權操作。
- 匯付提供API接口，支持支付寶、微信交易方式的預授權操作。
場景一：智能POS發起預授權演示
場景二：小程序、公眾號、APP等調用API接口，發起預授權;
1.3 名詞定義及說明
預授權：預付款，商戶估算了用戶的消費金額之后，在用戶賬戶、銀行卡內凍結相應的金額，等用戶消費完成后，商戶再進行正式結算，相當于押金
2. 接入前準備
2.1 商務準備
-
選擇接入模式
-
直簽模式：指商戶與匯付直接簽約。具體流程：商戶完成協議簽署后，商戶需要準備好入網材料提供給匯付銷售人員，匯付收到后會盡快為商戶發起入網申請，待審核通過入網成功后，商戶聯系人將收到短信通知控臺賬號及密碼。
-
服務商模式：指服務商與匯付簽約，服務商通過接口或控臺方式完成商戶入網。具體流程：服務商完成協議簽署后，服務商需要準備好入網材料提供給匯付銷售人員，匯付收到后會盡快為服務商發起入網申請，待審核通過入網成功后，服務商聯系人將收到短信通知控臺賬號及密碼。
-
在斗拱完成商戶進件入網
-
直簽模式：已有匯付銷售人員申請開通，商戶無須另行操作；
-
服務商模式：
- 控臺入網：參考服務商控臺進件流程，渠道商接入指引；
- API入網：企業商戶調用企業商戶基本信息入駐接口 、小微商戶調用個人商戶基本信息入駐接口 完成開戶、綁卡、結算配置。
2.2 對接準備
第一步：密鑰獲取
聯調之前需要先獲取公私鑰，參見公私解鑰參數獲取說明；
第二步：公共參數獲取
登錄服務商/商戶控臺后，可在開發設置-開發者信息中，獲取sys_id，product_id參數信息;
第三步：業務開通及配置
- 控臺開通
- 匯付運營人員幫助渠道商開通預授權業務權限；進行支付寶支付、微信支付、銀行卡支付-支付功能開通；
- 渠道商給商戶開通預授權：
開通微信預授權：僅支持線下場景且行業為7011-住宿服務、7512-汽車出租、7296-服裝出租
開通支付寶預授權：僅支持線下場景且行業為7011-住宿服務、7512-汽車出租、7296-服裝出租
路徑：渠道商控臺-【商戶管理】->【商戶信息變更】
選擇商戶，操作-業務變更
配置修改：業務配置
風險控制模塊：
是否開通刷卡預授權、是否開通支付寶預授權、是否開通微信預授權
- 接口開通
通過調用 商戶業務開通 接口開通支付寶，微信預授權功能（刷卡預授權只能控臺開通）
3. 開發指引
3.1 對接規范
調用匯付接口，均采取POST形式提交，數據格式統一為JSON格式，相關SDK及簽名方法見鏈接：
SDK示例：Java SDK
加簽驗簽：v2版接口加簽驗簽
3.2 確認業務配置
登錄控臺查詢預授權是否配置完成
- 通過服務商控臺-【商戶管理】-【商戶信息】-查詢-業務配置
- 商戶控臺-【我的信息管理】-【我的信息】-業務信息
- 通過商戶詳細信息查詢接口來確認相關配置。
3.3 系統調用流程
3.3.1 交易流程
適用對象：需要通過接口實現微信、支付寶預授權功能的商戶。（POS終端的請參考終端指引文檔）
小程序、公眾號、APP等調用API接口進行微信支付寶預授權支付功能：預授權交易發起、預授權交易撤銷、預授權交易完成、預授權交易撤銷完成。
交易流程圖：
交易步驟：
預授權交易入參需關注以下字段：
| 參數 | 中文名 | 必填 | 說明 |
|---|---|---|---|
| auth_code | 支付授權碼 | Y | 掃碼設備讀出的條形碼或者二維碼信息； 示例值：2884138408701518074 |
| limit_pay_type | 禁用信用卡標記 | N | NO_CREDIT禁用信用卡，為空默認不禁用； 示例值：NO_CREDIT |
| notify_url | 異步通知地址 | N | 交易異步通知地址，http或https開頭； 示例值：https://callback.service.com/xx |
預授權交易完成 入參需關注以下字段：
| 參數 | 中文名 | 必填 | 說明 |
|---|---|---|---|
| org_req_date | 原交易請求日期 | Y | 日期格式：yyyyMMdd |
| org_auth_no | 原授權號 | N | 原預授權交易請求流水號、原授權號、原預授權全局流水號三選一 |
| org_req_seq_id | 原預授權交易請求流水號 | N | 原預授權交易請求流水號、原授權號、原預授權全局流水號三選一 |
| pre_auth_hf_seq_id | 預授權匯付全局流水號 | N | 預授權匯付全局流水號 |
- 預授權交易以及交易完成查詢，可通過掃碼交易查詢接口進行查詢。
3.3.2 撤銷流程
預授權交易撤銷入參需關注以下字段：
| 參數 | 中文名 | 必填 | 說明 |
|---|---|---|---|
| org_auth_no | 原授權號 | N | orgReqSeqId,和authNo、preAuthHfSeqId三選一 |
| org_req_date | 原交易請求日期 | Y | 請求格式：yyyyMMdd |
| org_req_seq_id | 原交易請求流水號 | N | orgReqSeqId,和authNo、preAuthHfSeqId三選一 |
| pre_auth_hf_seq_id | 原預授權全局流水號 | N | orgReqSeqId,和authNo、preAuthHfSeqId三選一 |
預授權交易完成撤銷 入參需關注以下字段：
| 參數 | 中文名 | 必填 | 說明 |
|---|---|---|---|
| org_req_date | 原預授權完成交易請求日期 | Y | 請求格式：yyyyMMdd |
| org_req_seq_id | 原預授權完成交易請求流水號 | N | 原預授權完成交易請求流水號 |
- 預授權交易撤銷以及完成撤銷查詢，可通過掃碼交易退款查詢進行查詢
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列表
| 類型 | 功能 | 描述 |
|---|---|---|
| 應用程序接口 | 微信支付寶預授權 | 商戶微信、支付寶預授權交易發起。 |
| 應用程序接口 | 微信支付寶預授權撤銷 | 商戶微信、支付寶預授權交易撤銷。 |
| 應用程序接口 | 微信支付寶預授權完成 | 商戶微信、支付寶預授權交易完成。 |
| 應用程序接口 | 微信支付寶預授權完成撤銷 | 商戶微信、支付寶預授權交易完成撤銷。 |
| 應用程序接口 | 掃碼交易查詢接口 | 主動查詢訂單狀態。 |
| 應用程序接口 | 掃碼交易退款查詢 | 查詢退款/撤銷結果。 |
5.常見問題
- 支付接口調用報錯：“resp_desc”：“數據權限認證失敗”
問題原因：商戶信息校驗沒有通過。
解決方案：
1）檢查報文中的產品號（product_id）是否填寫正確;
2）檢查報文中的系統號（sys_id）和商戶號（huifu_Id） 從屬關系是否正確。
更多問題詳見斗拱開發者社區：https://service.dougong.net/t/qa
