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