快捷支付
最近更新時間：2023.9.16
1. 產品介紹
1.1 簡介
持卡人無需登錄網上銀行，可直接輸入卡面信息及持卡人身份信息。根據安全規則通過驗證銀行預留的手機接收校驗碼完成簽約或支付，是一種便捷、快速、安全的付款方式，主要用于PC網站或移動端銀行卡支付。
1.2 應用場景
商戶如果想在自己的業務場景中擺脫對微信、支付寶的依賴，獲取用戶信息以便提供更好的服務可以選擇快捷。或者將快捷深度融合到自己的業務場景中，比如整合自己的積分、營銷服務等，可以選擇快捷。斗拱提供了兩種接口模式：
- 純接口模式：包括綁卡、短信預校驗、支付申請、支付確認等一系列接口，可以靈活地打造操作流程整合進業務流程中。
- 帶頁面的快捷接口，一個接口拉起支付頁面完成整個支付流程，簡單方便。
可以通過斗拱演示體驗了解快捷支付在PC網站、APP、H5頁面中的效果。
2. 接入前準備
2.1 商務準備
-
選擇接入模式
-
直簽模式：指商戶與匯付直接簽約。具體流程：商戶完成協議簽署后，商戶需要準備好入網材料提供給匯付銷售人員，匯付收到后會盡快為商戶發起入網申請，待審核通過入網成功后，商戶聯系人將收到短信通知控臺賬號及密碼。
-
服務商模式：指服務商與匯付簽約，服務商通過接口或控臺方式完成商戶入網。具體流程：服務商完成協議簽署后，服務商需要準備好入網材料提供給匯付銷售人員，匯付收到后會盡快為服務商發起入網申請，待審核通過入網成功后，服務商聯系人將收到短信通知控臺賬號及密碼。
-
客戶要準備好線上業務場景，快捷支付可以集成到PC網站、APP、H5頁面的線上場景中。
-
在斗拱完成商戶進件入網
- 直簽模式：已有匯付銷售人員申請開通，商戶無須另行操作；
- 服務商模式：
- 控臺入網：參考服務商控臺進件流程，渠道商接入指引；
- API入網：企業商戶調用企業商戶基本信息入駐接口 、小微商戶調用個人商戶基本信息入駐接口 完成開戶、綁卡、結算配置。
-
選擇接入功能并準備相關材料
- 快捷支付能力：
- 直簽模式：聯系匯付銷售人員申請開通，商戶無須另行操作；
- 服務商模式：聯系匯付銷售人員申請開通服務商快捷支付權限，開通后給予所屬商戶開通相關權限；
- 快捷支付能力：
2.2 對接準備
第一步：密鑰獲取
聯調之前需要先獲取公私鑰，參見公私解鑰參數獲取說明；
第二步：公共參數獲取
登錄服務商/商戶控臺后，可在開發設置-開發者信息中，獲取sys_id，product_id參數信息；（如控臺未展示，請聯系對接群內匯付技術助手提供）
第三步：業務開通及配置
直簽商戶聯系銷售即可；
- 控臺開通
服務商控臺【商戶管理】【信息查詢】【商戶信息（新）】【業務信息編輯】【支付功能】開通快捷支付、配置相關費率
- 接口開通
調用 商戶業務開通 接口開通快捷支付。具體流程請參考API文檔，商戶進件。
3. 開發指引
3.1 對接規范
調用匯付接口，均采取POST形式提交，數據格式統一為JSON格式，相關SDK及簽名方法見鏈接：
SDK示例：Java SDK
加簽驗簽：v2版接口加簽驗簽
3.2 確認業務配置
控臺查詢快捷支付是否配置完成
- 通過服務商控臺【商戶信息查詢】【產品信息TAB頁面】查看【快捷】
- 商戶控臺【我的信息】
- 通過商戶詳細信息查詢接口來確認相關配置。
3.3 系統調用流程
3.3.1 交易流程
- 頁面模式：調用快捷支付頁面版接口，由于流程已封裝不再描述；可進行斗拱演示體驗，了解快捷支付在PC網站、APP、H5頁面中的效果。
- 純接口模式：
由于商戶業務場景的差異，上圖描述的只是快捷的標準流程，具體流程商戶在不變更操作順序的情形下可以結合實際調整。
接入步驟說明：
- 快捷支付前需要用戶先完成綁卡，綁卡流程如下：
- 快捷支付流程分為兩階段；
- 商戶會跳到業務系統頁面。
快捷綁卡申請接口
入參需關注以下字段：
| 參數 | 中文名 | 必填 | 說明 |
|---|---|---|---|
| order_id | 訂單號 | Y | 綁卡申請訂單號 |
| out_cust_id | 商戶用戶id | Y | 用戶在商戶側注冊商戶生成的用戶號；同一用戶不要反復注冊不同的用戶id； |
| card_id | 銀行卡號 | Y | 需要密文傳輸，使用匯付RSA公鑰加密(加密前64位，加密后最長2048位） |
| card_name | 銀行卡開戶姓名 | Y | 需要密文傳輸，使用匯付RSA公鑰加密(加密前64位，加密后最長2048位） |
| cert_id | 銀行卡綁定身份證 | Y | 需要密文傳輸，使用匯付RSA公鑰加密(加密前64位，加密后最長2048位） |
| card_mp | 銀行卡綁定手機號 | Y | 需要密文傳輸，使用匯付RSA公鑰加密(加密前64位，加密后最長2048位） |
| vip_code | CVV2 | C | 信用卡交易專用需要密文傳輸。 |
| expiration | 卡有效期 | C | 信用卡交易專用，格式：MMYY，需要密文傳輸； |
| dc_type | 卡的借貸類型 | N | C:信用卡,D:借記卡,S:準貸記,U:未知卡； |
| protocol_no | 掛網協議編號 | C | 授權信息(招行綁卡需要上送)； |
快捷綁卡確認接口
入參需關注以下字段：
| 參數 | 中文名 | 必填 | 說明 |
|---|---|---|---|
| order_id | 訂單號 | Y | 快捷綁卡申請接口的入參綁卡申請訂單號order_id |
| verify_code | 驗證碼 | Y | 短信驗證碼 |
返參需關注字段：
| 參數 | 中文名 | 說明 |
|---|---|---|
| trans_status | 交易狀態 | 綁卡狀態，I:初始化,P:處理中,S:成功,F:失敗 |
| cust_id | 用戶號 | 綁卡成功后會獲取用戶客戶號，參見快捷綁卡確認接口/一鍵綁卡接口的返參cust_id字段； |
| token_no | 綁卡序列號 | 后續快捷支付以token_no代表已綁定的卡 |
快捷支付申請
入參需關注以下字段：
| 參數 | 中文名 | 必填 | 說明 |
|---|---|---|---|
| card_bind_id | 綁卡id | Y | 綁卡成功后會獲取綁卡id，參見快捷綁卡確認接口/一鍵綁卡接口的返參token_no字段； |
| user_huifu_id | 用戶客戶號 | Y | 綁卡成功后會獲取用戶客戶號，參見快捷綁卡確認接口/一鍵綁卡接口的返參cust_id字段； |
| order_type | 訂單類型 | N | P：支付; R：充值, 默認：P |
| time_expire | 訂單失效時間 | N | 格式：yyyyMMddHHmmss,注：工商銀行需傳90min以上方能成功 |
返參需關注字段：
| 參數 | 中文名 | 說明 |
|---|---|---|
| avoid_sms_flag | 免短標簽 | 如是 3，則無需調用確認接口 |
快捷支付確認
入參需關注以下字段：
| 參數 | 中文名 | 必填 | 說明 |
|---|---|---|---|
| sms_code | 短信驗證碼 | Y | 用戶提供6位短信驗證碼； |
異步返回關注以下字段：
| 參數 | 中文名 | 說明 |
|---|---|---|
| trans_stat | 交易狀態 | I:處理中(初始化)，P：處理中，S：成功，F：失敗； |
| acct_stat | 賬務狀態 | 可能因為手續費不足的原因存在交易成功賬務失敗的情況。這種情況可以聯系匯付運營人員解決； |
3.3.2 退款流程
完整的交易流程還要包括退款。由于用戶或者商戶的原因需要退款時，商戶可以通過本接口將支付款退還給用戶，退款成功資金將原路返回。
參見線上交易退款接口；
關注以下請參：
| 參數 | 中文名 | 必填 | 說明 |
|---|---|---|---|
| org_req_date | 原交易請求日期 | Y | 用戶發起支付的日期 |
| org_req_seq_id | 原交易請求流水號 | C | 商戶系統發給斗拱的指令流水號 |
| org_hf_seq_id | 原交易全局流水號 | C | 匯付生成的系統流水號 |
| ord_amt | 申請退款金額 | Y | 退款金額<=原交易金額 |
- 原交易請求流水號、原交易全局流水號、原交易微信支付寶的商戶單號三選一即可；
- 退款金額不能大于交易金額；由于接口支持多次部分退款，多次退款場景下退款總額不能高于原交易金額；
- 退款也是以異步返回的成功或失敗狀態為最終結果；
- 一些特殊場景下退款時效可能比較長，注意接口描述文檔中的退款時效說明；
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列表
| 類型 | 功能 | 描述 |
|---|---|---|
| API | 快捷支付頁面版 | 快捷支付三合一頁面版，只需一次短信驗證碼，系統自動完成綁卡支付 |
| API | 快捷綁卡申請接口 | 綁卡流程第一步 |
| API | 快捷綁卡確認接口 | 綁卡流程第二步 |
| API | 快捷解綁接口 | 解綁卡 |
| API | 快捷綁卡查詢 | 查詢已綁定的卡 |
| API | 快捷支付申請接口 | 商戶系統調用該接口發起快捷支付申請，斗拱平臺會向持卡人在銀行預留的手機號發送短信驗證碼， 支持營銷補貼功能 |
| API | 快捷支付確認接口 | 商戶系統調用快捷支付確認接口，上送短信驗證碼，完成支付。 |
| API | 線上交易查詢接口 | 查詢單筆線上交易狀態及明細 |
| API | 線上交易退款接口 | 支持線上交易全額或部分退款 營銷補貼退款：支持全額退款、銀行卡退款，不支持單獨退補貼金額 |
| API | 線上退款查詢接口 | 查詢單筆線上退款狀態及明細 |
| API | 電子回單查詢 | 查看、下載快捷支付交易的回單 |
5.常見問題
- 【快捷綁卡申請】接口報錯：“resp_code”：“00000003”，“resp_desc”：“已超過最大查詢次數或操作過于頻繁”
快捷綁卡要素驗證，連續失敗 3 次以上。
解決方案
核實要素確實沒有問題，可 24 小時后再發起重試。
- 支付接口調用報錯：“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' 表示交易成功-入賬失敗（非正常情況，可聯系匯付技術人員確認排查）
更多問題詳見斗拱開發者社區：https://service.dougong.net/t/qa
