支付寶支付

最近更新時間：2023.9.21

1. 產(chǎn)品介紹

1.1 簡介

斗拱為手機、平板、POS等智能終端的APP提供支付服務接口。斗拱收款、查詢、結(jié)算、對賬的完整流程服務。

匯付支付支持在主流應用市場完成認證的移動端應用APP接入支付功能。APP接入支付后，商戶通過斗拱支付接口調(diào)用支付寶支付完成收款需求。目前支持手機系統(tǒng)有：IOS（蘋果）、Android（安卓）。

1.2 應用場景

客戶擁有自己的一個APP，為了使APP接入支付功能實現(xiàn)商業(yè)上的閉環(huán)，商戶APP跳轉(zhuǎn)支付寶成交易。

支付寶APP 支付可通過如下兩種方式實現(xiàn)，核心是獲取支付寶給的“憑證”。

• 通過支付寶掃碼實現(xiàn)（Native支付）：參見本文3.3.1-支付寶NATIVE支付。
• 通過支付寶手機網(wǎng)站（JS支付）實現(xiàn)：參見本文3.3.2-支付寶JS支付（利用支付寶JS實現(xiàn)APP支付，需準備一個支付寶小程序）。

支付寶手機網(wǎng)站（JS）支付頁面

可以通過斗拱演示APP體驗了解支付寶支付在演示APP中的效果;下圖是演示APP下載的鏈接。

2. 接入前準備

2.1 商務準備

1. 客戶首先要有APP，APP已經(jīng)在公開市場上架

2. 選擇接入模式

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

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

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

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

6. 選擇接入功能并準備相關(guān)材料

   1. 支付寶支付；

2.2 對接準備

第一步：密鑰獲取

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

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

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

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

• 服務商模式：

步驟一：服務商功能及權(quán)限開通。服務商通過線下簽約方式申請支付寶功能，匯付運營人員在審核好服務商資料之后，為服務商開通相關(guān)支付功能，及費率配置。

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

•  直簽商戶：

與客戶經(jīng)理確認已開通功能及相關(guān)費率配置。

3. 開發(fā)指引

3.1 對接規(guī)范

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

SDK示例：Java SDK

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

3.2 業(yè)務開發(fā)配置

商戶的APP需要通過拉起支付寶手機網(wǎng)站支付完成支付操作

3.2.1 支付寶側(cè)接入準備：

1. 如選擇支付寶native支付模式，無需提前準備；
2. 如選擇支付寶JS支付模式，需要申請一個支付寶小程序并獲取app_id；

3.2.2 斗拱側(cè)準備:

1. 商戶支付寶業(yè)務及費率已配置；（如已與客戶經(jīng)理確認，該步驟可忽略）

查詢方式

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

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

2. 支付寶實名認證狀態(tài)已完成，實名認證狀態(tài)顯示已授權(quán)（支付寶側(cè)實際完成即可，斗拱控臺可能存在狀態(tài)更新不及時）

查詢方式

1）服務商控臺：【商戶信息】

2）通過支付寶實名認證狀態(tài)查詢接口來確認相關(guān)配置。

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

3.3.1 NATIVE支付方式接入流程

此種方式的主要原理是：通過拉起支付寶APP 然后調(diào)用支付寶內(nèi)said為10000007的掃碼功能來發(fā)起支付，下單獲取支付payinfo信息

接入步驟說明：

第一步：調(diào)用 聚合正掃 接口時trade_type: A_NATIVE(支付寶正掃)

第二步：前端拿到服務端返回的payinfo信息中的qr_code，在 APP 內(nèi) 通過打開第三方APP的方式打開此URL

第三步：取出接口返回的qr_code，在 APP 內(nèi) 通過打開第三方APP的方式打開如下URL

第四步：獲取終態(tài)，客戶支付完成后匯付會將支付結(jié)果推送到客戶異步地址，如果長時間未收到異步結(jié)果可以調(diào)用掃碼交易查詢接口查詢交易狀態(tài)

示例：

alipays://platformapi/startapp?saId=10000007&qrcode=https://qr.alipay.com/bax02911brluc2xieoph6001復制代碼復制失敗復制成功

Android 示例代碼：

    // 固定前綴
    String topic = "alipays://platformapi/startapp?saId=10000007&qrcode=";
    // 從匯付正掃接口獲取的參數(shù)（以下值僅為示例）
    String qrcodeUrl = "https://qr.alipay.com/bax02911brluc2xieoph6001"
    // 字符串拼接
    String jumpUrl = topic + qrcodeUrl;
    // 按以上示例拼接得出結(jié)果
    // jumpUrl 為 alipays://platformapi/startapp?saId=10000007&qrcode=https://qr.alipay.com/bax02911brluc2xieoph6001
    Intent intent = new Intent();
    intent.setAction("android.intent.action.VIEW");
    // jumpUrl 為先前示例中拼裝的 url
    Uri contentUrl = Uri.parse(jumpUrl);
    intent.setData(contentUrl);
    activity.startActivity(intent);復制代碼復制失敗復制成功

IOS示例代碼：

 [[UIApplication sharedApplication]openURL:[NSURL URLWithString: jumpUrl]];復制代碼復制失敗復制成功

注意事項：

a.系統(tǒng)會彈出是否允許打開支付寶，點擊允許，跳轉(zhuǎn)支付寶進行支付，此種方式?jīng)]有考慮用戶沒有裝支付寶的情況。

b.如需考慮未安裝支付寶的情況，APP端可使用 webview，加載聚合正掃接口返回的鏈接（例：https://qr.alipay.com/bax02911brluc2xieoph6001） 此種方式，如未安裝支付寶客戶端，會跳轉(zhuǎn)到支付寶下載頁面，引導用戶安裝下載。

c.以上部分是在APP為原生開發(fā)的前提下，RN的方式參考以下示例，Union App開發(fā)的可參考以上實現(xiàn)思路來實現(xiàn)，匯付無具體代碼案例。

d.React Native方式可參考如下

    linkurl = 'alipays://platformapi/startapp?saId=10000007&qrcode='+ {URL}
    Linking.openURL(linkurl);復制代碼復制失敗復制成功

3.3.2 JS支付方式接入流程

此種方式的主要原理是：通過拉起支付寶APP，然后跳轉(zhuǎn)到對應支付寶小程序中完成支付。

接入步驟說明：

第一步：APP端打開第三方APP的方式打開如下URL

alipays://platformapi/startapp?appId=app_id&page=page_path"復制代碼復制失敗復制成功

其中appid 為在支付寶側(cè)申請的小程序appid，page_path 為跳轉(zhuǎn)過去的小程序頁面路徑

第二步：獲取 buyer_id，即付款用戶的支付寶 user_id，詳情參考支付寶官方文檔： [用戶授權(quán)](https://opendocs.alipay.com/mini/introduce/authcode#第一步：客戶端獲取 authcode)        

1. 小程序客戶端內(nèi)獲取 authorization_code 示例：

    my.getAuthCode({
    scopes: ['auth_user'],
    // 主動授權(quán)：auth_user，靜默授權(quán)：auth_base?；蛘咂渌黶cope。如需同時獲取用戶多項授權(quán)，可在 scopes 中傳入多個 scope 值。
    success: (res) => {
            if (res.authCode) {
            // 認證成功
            // 調(diào)用自己的服務端接口，讓服務端進行后端的授權(quán)認證，并且利用session，需要解決跨域問題
            my.request({
                url: 'https://isv.com/auth', // 該url是您自己的服務地址，實現(xiàn)的功能是服務端拿到authcode去開放平臺進行token驗證
                data: {
                authcode: res.authCode,
                },
                success: () => {
                // 授權(quán)成功并且服務器端登錄成功
                },
                fail: () => {
                // 根據(jù)自己的業(yè)務場景來進行錯誤處理
                },
            });
            }
        },
    });復制代碼復制失敗復制成功

2. 商戶服務端獲取 access_token、user_id

服務器端調(diào)用 alipay.system.oauth.token(換取授權(quán)訪問令牌) 接口換取授權(quán)訪問令牌，開發(fā)者可通過獲取到的 auth_code 換取 access_token（授權(quán)令牌） 和 user_id（用戶支付寶 ID）。

auth_code 作為換取 access_token 的票據(jù)，每次用戶授權(quán)完成，回調(diào)地址中的 auth_code 將不一樣，auth_cod 只能使用一次，一天未被使用自動過期。

    AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
    AlipaySystemOauthTokenRequest request = new AlipaySystemOauthTokenRequest();
    request.setGrantType("authorization_code");
    request.setCode("4b203fe6c11548bcabd8da5bb087a83b");
    AlipaySystemOauthTokenResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        System.out.println("調(diào)用成功");
    } else {
        System.out.println("調(diào)用失敗");
    }復制代碼復制失敗復制成功

參見：https://opendocs.alipay.com/mini/00g4c1

第三步：商戶小程序服務端調(diào)用匯付 聚合正掃 接口時trade_type: A_JSAPI (支付寶JS)，獲取支付信息，匯付下單成功會同步返回支付信息中包含tradeNO。

第四步：喚起收銀臺支付

在小程序端使用 tradeNO，調(diào)用 my.tradePay 接口喚起支付寶收銀臺，引導用戶完成支付。詳情參見支付寶官方說明： 小程序喚起收銀臺

    my.tradePay({
        tradeNO: '2017111521001104105336677922',
        success: function(res) {
          my.alert({
           content: JSON.stringify(res),
         });
        },
        fail: function(res) {
        my.alert({
          content: JSON.stringify(res),
          });
       },
    });復制代碼復制失敗復制成功

第五步：獲取終態(tài)

客戶支付完成后匯付會將支付結(jié)果推送到客戶異步地址，如果長時間未收到異步結(jié)果可以調(diào)用掃碼交易查詢接口查詢交易狀態(tài)；

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

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

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

3.3.3 退款流程

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

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

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

3.3.4 對賬流程

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

方案一：控臺下載；

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

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

3.3.5 異步通知

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

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

注意事項：

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

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

詳見異步通知使用說明。

4. API列表

5.常見問題

1. 支付時，接口報錯:”當前商戶需補齊相關(guān)資料后，才可進行相應的支付交易 ”

問題原因：此錯誤一般是商戶還沒有完成實名認證。

解決方案：完成支付寶實名認證

1).渠道商控臺進行實名認證，菜單如圖：

2).掃拓展碼進行實名驗證（可聯(lián)系匯付人員指導）

3).通過接口進行實名認證：

實名認證接口：https://paas.huifu.com/partners/api/#/shgl/shjj/api_shjj_zfbsmrz

2. 支付寶實名認證返回：參數(shù)有誤參數(shù)不正確： ILLEGAL_PARAMETER：商戶smid已完成認證

已線下完成實名認證，無需再次實名。

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

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

解決方案：

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

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

4. 為什么交易成功以后會收到 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' 表示交易成功-入賬失敗

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