支付寶支付

最近更新時(shí)間：2023.9.21

1. 產(chǎn)品介紹

1.1 簡(jiǎn)介

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

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

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

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

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

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

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

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

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

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

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

2. 選擇接入模式

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

4. 服務(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)及密碼。

5. 在斗拱完成商戶進(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)：企業(yè)商戶調(diào)用企業(yè)商戶基本信息入駐接口 、小微商戶調(diào)用個(gè)人商戶基本信息入駐接口 完成開戶、綁卡、結(jié)算配置。

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

   1. 支付寶支付；

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)支付寶功能，匯付運(yùn)營(yíng)人員在審核好服務(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)參考商戶進(jìn)件說明。

•  直簽商戶：

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

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 業(yè)務(wù)開發(fā)配置

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

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

1. 如選擇支付寶native支付模式，無需提前準(zhǔn)備；
2. 如選擇支付寶JS支付模式，需要申請(qǐng)一個(gè)支付寶小程序并獲取app_id；

3.2.2 斗拱側(cè)準(zhǔn)備:

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

查詢方式

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

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

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

查詢方式

1）服務(wù)商控臺(tái)：【商戶信息】

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

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

3.3.1 NATIVE支付方式接入流程

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

接入步驟說明：

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

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

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

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

示例：

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

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);復(fù)制代碼復(fù)制失敗復(fù)制成功

IOS示例代碼：

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

注意事項(xiàng)：

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

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

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

d.React Native方式可參考如下

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

3.3.2 JS支付方式接入流程

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

接入步驟說明：

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

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

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

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

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

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

2. 商戶服務(wù)端獲取 access_token、user_id

服務(wù)器端調(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 只能使用一次，一天未被使用自動(dòng)過期。

    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)用失敗");
    }復(fù)制代碼復(fù)制失敗復(fù)制成功

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

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

第四步：喚起收銀臺(tái)支付

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

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

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

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

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

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

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

3.3.3 退款流程

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

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

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

3.3.4 對(duì)賬流程

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

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

方案二：接口獲?。粎⒁?a target="_blank" rel="noopener">交易結(jié)算對(duì)賬單查詢接口

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

3.3.5 異步通知

針對(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. 支付時(shí)，接口報(bào)錯(cuò):”當(dāng)前商戶需補(bǔ)齊相關(guān)資料后，才可進(jìn)行相應(yīng)的支付交易 ”

問題原因：此錯(cuò)誤一般是商戶還沒有完成實(shí)名認(rèn)證。

解決方案：完成支付寶實(shí)名認(rèn)證

1).渠道商控臺(tái)進(jìn)行實(shí)名認(rèn)證，菜單如圖：

2).掃拓展碼進(jìn)行實(shí)名驗(yàn)證（可聯(lián)系匯付人員指導(dǎo)）

3).通過接口進(jìn)行實(shí)名認(rèn)證：

實(shí)名認(rèn)證接口：https://paas.huifu.com/partners/api/#/shgl/shjj/api_shjj_zfbsmrz

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

已線下完成實(shí)名認(rèn)證，無需再次實(shí)名。

3. 支付接口調(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)系是否正確。

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

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