支付寶 服務(wù)器同步/異步通知參數(shù)說明

本章節(jié)詳細(xì)說明支付寶APP支付服務(wù)器同步、異步的通知參數(shù)說明。

• 同步通知：支付寶sdk對(duì)商戶的請(qǐng)求支付數(shù)據(jù)處理完成后，會(huì)將結(jié)果同步反饋給商戶app端。
• 異步通知：對(duì)于App支付產(chǎn)生的交易，支付寶會(huì)根據(jù)原始支付API中傳入的異步通知地址notify_url，通過POST請(qǐng)求的形式將支付結(jié)果作為參數(shù)通知到商戶系統(tǒng)。

一、同步通知參數(shù)說明

支付寶sdk對(duì)商戶的請(qǐng)求支付數(shù)據(jù)處理完成后，會(huì)將結(jié)果同步反饋給商戶app端。

同步返回的數(shù)據(jù)，商戶可以按照下文描述的方式在服務(wù)端驗(yàn)證，驗(yàn)證通過后，可以認(rèn)為本次用戶付款成功。有些時(shí)候會(huì)出現(xiàn)商戶app在支付寶付款階段被關(guān)閉導(dǎo)致無法正確收到同步結(jié)果，此時(shí)支付結(jié)果可以完全依賴服務(wù)端的異步通知。

由于同步通知和異步通知都可以作為支付完成的憑證，且異步通知支付寶一定會(huì)確保發(fā)送給商戶服務(wù)端。為了簡(jiǎn)化集成流程，商戶可以將同步結(jié)果僅僅作為一個(gè)支付結(jié)束的通知（忽略執(zhí)行校驗(yàn)），實(shí)際支付是否成功，完全依賴服務(wù)端異步通知。

返回結(jié)果示例（iOS|Android）

對(duì)于iOS平臺(tái)而言返回參數(shù)是一個(gè)NSDictionary對(duì)象，對(duì)于Android平臺(tái)而言是一個(gè)map結(jié)構(gòu)體。里面有三個(gè)key，其中memo是描述信息(類型為字符串)；result是處理結(jié)果(類型為json結(jié)構(gòu)字符串)；resultStatus是結(jié)果碼(類型為字符串)。

{
    "memo" : "xxxxx",
    "result" : "{
                    \"alipay_trade_app_pay_response\":{
                        \"code\":\"10000\",
                        \"msg\":\"Success\",
                        \"app_id\":\"2014072300007148\",
                        \"out_trade_no\":\"081622560194853\",
                        \"trade_no\":\"2016081621001004400236957647\",
                        \"total_amount\":\"0.01\",
                        \"seller_id\":\"2088702849871851\",
                        \"charset\":\"utf-8\",
                        \"timestamp\":\"2016-10-11 17:43:36\"
                    },
                    \"sign\":\"NGfStJf3i3ooWBuCDIQSumOpaGBcQz+aoAqyGh3W6EqA/gmyPYwLJ2REFijY9XPTApI9YglZyMw+ZMhd3kb0mh4RAXMrb6mekX4Zu8Nf6geOwIa9kLOnw0IMCjxi4abDIfXhxrXyj********\",
                    \"sign_type\":\"RSA2\"
                }",
    "resultStatus" : "9000"
}

返回結(jié)果參數(shù)

resultStatus結(jié)果碼含義

同步通知驗(yàn)證

為了幫助開發(fā)者調(diào)用開放接口，我們提供了開放平臺(tái)服務(wù)端DEMO&SDK，包含JAVA、PHP和.NET三語言版本，封裝了簽名&驗(yàn)簽、HTTP接口請(qǐng)求等基礎(chǔ)功能。強(qiáng)烈建議先下載對(duì)應(yīng)語言版本的SDK并引入您的開發(fā)工程進(jìn)行快速接入。

在返回?cái)?shù)據(jù)resultStatus為9000的情況下，解析result結(jié)果，提取驗(yàn)證簽名的相關(guān)核心數(shù)據(jù)：

第一步： 提取alipay_trade_app_pay_response字段值，其代表簽名原始字符串，上述示例格式如下：

{"code":"10000","msg":"Success","total_amount":"9.00","app_id":"2014072300007148","trade_no":"2014112400001000340011111118","seller_id":"2088111111116894","out_trade_no":"70501111111S001111119"}

第二步： 提取sign_type字段值，其代表簽名類型，上述示例格式如下：

RSA2

第三步： 提取sign字段值，其代表簽名結(jié)果，上述示例格式如下：

NGfStJf3i3ooWBuCDIQSumOpaGBcQz+aoAqyGh3W6EqA/gmyPYwLJ2REFijY9XPTApI9YglZyMw+ZMhd3kb0mh4RAXMrb6mekX4Zu8Nf6geOwIa9kLOnw0IMCjxi4abDIfXhxrXyj**** 第四步： 驗(yàn)證簽名是否合法：

使用各自語言對(duì)應(yīng)的SHA256WithRSA簽名驗(yàn)證函數(shù)，傳入簽名的原始字符串、支付寶公鑰、簽名類型RSA、簽名字符進(jìn)行合法性驗(yàn)證。

第五步： 在第四步簽名驗(yàn)證通過后，必須嚴(yán)格按照如下的描述校驗(yàn)通知參數(shù)的合法性：

1. 商戶需要驗(yàn)證該通知數(shù)據(jù)中的out_trade_no是否為商戶系統(tǒng)中創(chuàng)建的訂單號(hào)；
2. 判斷total_amount是否確實(shí)為該訂單的實(shí)際金額（即商戶訂單創(chuàng)建時(shí)的金額）；
3. 校驗(yàn)通知中的seller_id（或者seller_email) 是否為out_trade_no這筆單據(jù)對(duì)應(yīng)的操作方（有的時(shí)候，一個(gè)商戶可能有多個(gè)seller_id/seller_email）；
4. 驗(yàn)證app_id是否為該商戶本身。

上述1、2、3、4有任何一個(gè)驗(yàn)證不通過，則表明同步校驗(yàn)結(jié)果是無效的，只有全部驗(yàn)證通過后，才可以認(rèn)定買家付款成功。

二、異步通知參數(shù)說明

對(duì)于App支付產(chǎn)生的交易，支付寶會(huì)根據(jù)原始支付API中傳入的異步通知地址notify_url，通過POST請(qǐng)求的形式將支付結(jié)果作為參數(shù)通知到商戶系統(tǒng)。

異步通知參數(shù)

交易狀態(tài)說明

通知觸發(fā)條件

資金明細(xì)信息說明

支付渠道說明

優(yōu)惠券信息說明

服務(wù)器異步通知頁面特性

• 必須保證服務(wù)器異步通知頁面（notify_url）上無任何字符，如空格、HTML標(biāo)簽、開發(fā)系統(tǒng)自帶拋出的異常提示信息等；
• 支付寶是用POST方式發(fā)送通知信息，因此該頁面中獲取參數(shù)的方式，如：request.Form(“out_trade_no”)、$_POST[‘out_trade_no’]；
• 支付寶主動(dòng)發(fā)起通知，該方式才會(huì)被啟用；
• 只有在支付寶的交易管理中存在該筆交易，且發(fā)生了交易狀態(tài)的改變，支付寶才會(huì)通過該方式發(fā)起服務(wù)器通知（即時(shí)到賬交易狀態(tài)為“等待買家付款”的狀態(tài)默認(rèn)是不會(huì)發(fā)送通知的）；
• 服務(wù)器間的交互，不像頁面跳轉(zhuǎn)同步通知可以在頁面上顯示出來，這種交互方式是不可見的；
• 第一次交易狀態(tài)改變（即時(shí)到賬中此時(shí)交易狀態(tài)是交易完成）時(shí)，不僅會(huì)返回同步處理結(jié)果，而且服務(wù)器異步通知頁面也會(huì)收到支付寶發(fā)來的處理結(jié)果通知；
• 程序執(zhí)行完后必須打印輸出“success”（不包含引號(hào)）。如果商戶反饋給支付寶的字符不是success這7個(gè)字符，支付寶服務(wù)器會(huì)不斷重發(fā)通知，直到超過24小時(shí)22分鐘。一般情況下，25小時(shí)以內(nèi)完成8次通知（通知的間隔頻率一般是：4m,10m,10m,1h,2h,6h,15h）；
• 程序執(zhí)行完成后，該頁面不能執(zhí)行頁面跳轉(zhuǎn)。如果執(zhí)行頁面跳轉(zhuǎn)，支付寶會(huì)收不到success字符，會(huì)被支付寶服務(wù)器判定為該頁面程序運(yùn)行出現(xiàn)異常，而重發(fā)處理結(jié)果通知；
• cookies、session等在此頁面會(huì)失效，即無法獲取這些數(shù)據(jù)；
• 該方式的調(diào)試與運(yùn)行必須在服務(wù)器上，即互聯(lián)網(wǎng)上能訪問；
• 該方式的作用主要防止訂單丟失，即頁面跳轉(zhuǎn)同步通知沒有處理訂單更新，它則去處理；
• 當(dāng)商戶收到服務(wù)器異步通知并打印出success時(shí)，服務(wù)器異步通知參數(shù)notify_id才會(huì)失效。也就是說在支付寶發(fā)送同一條異步通知時(shí)（包含商戶并未成功打印出success導(dǎo)致支付寶重發(fā)數(shù)次通知），服務(wù)器異步通知參數(shù)notify_id是不變的。

異步返回結(jié)果的驗(yàn)簽

為了幫助開發(fā)者調(diào)用開放接口，我們提供了開放平臺(tái)服務(wù)端DEMO&SDK，包含JAVA、PHP和.NET三語言版本，封裝了簽名&驗(yàn)簽、HTTP接口請(qǐng)求等基礎(chǔ)功能。強(qiáng)烈建議先下載對(duì)應(yīng)語言版本的SDK并引入您的開發(fā)工程進(jìn)行快速接入。

某商戶設(shè)置的通知地址為https://api.xx.com/receive_notify.htm，對(duì)應(yīng)接收到通知的示例如下： 注：以下示例報(bào)文僅供參考，實(shí)際返回的詳細(xì)報(bào)文請(qǐng)以實(shí)際返回為準(zhǔn)。

https://api.xx.com/receive_notify.htm?total_amount=2.00&buyer_id=2088102116773037&body=大樂透2.1&trade_no=2016071921001003030200089909&refund_fee=0.00¬ify_time=2016-07-19 14:10:49&subject=大樂透2.1&sign_type=RSA2&charset=utf-8¬ify_type=trade_status_sync&out_trade_no=0719141034-6418&gmt_close=2016-07-19 14:10:46&gmt_payment=2016-07-19 14:10:47&trade_status=TRADE_SUCCESS&version=1.0&sign=kPbQIjX+xQc8F0/A6/AocELIjhhZnGbcBN6G4MM/HmfWL4ZiHM6fWl5NQhzXJusaklZ1LFuMo+lHQUELAYeugH8LYFvxnNajOvZhuxNFbN2LhF0l/KL8ANtj8oyPM4NN7Qft2kWJTDJUpQOzCzNnV9hDxh5AaT9FPqRS6ZKxnzM=&gmt_create=2016-07-19 14:10:44&app_id=2015102700040153&seller_id=2088102119685838¬ify_id=4a91b7a78a503640467525113fb7d8bg8e

第一步： 在通知返回參數(shù)列表中，除去sign、sign_type兩個(gè)參數(shù)外，凡是通知返回回來的參數(shù)皆是待驗(yàn)簽的參數(shù)。

第二步： 將剩下參數(shù)進(jìn)行url_decode, 然后進(jìn)行字典排序，組成字符串，得到待簽名字符串：

app_id=2015102700040153&body=大樂透2.1&buyer_id=2088102116773037&charset=utf-8&gmt_close=2016-07-19 14:10:46&gmt_payment=2016-07-19 14:10:47¬ify_id=4a91b7a78a503640467525113fb7d8bg8e¬ify_time=2016-07-19 14:10:49¬ify_type=trade_status_sync&out_trade_no=0719141034-6418&refund_fee=0.00&seller_id=2088102119685838&subject=大樂透2.1&total_amount=2.00&trade_no=2016071921001003030200089909&trade_status=TRADE_SUCCESS&version=1.0

第三步： 將簽名參數(shù)（sign）使用base64解碼為字節(jié)碼串。

第四步： 使用RSA的驗(yàn)簽方法，通過簽名字符串、簽名參數(shù)（經(jīng)過base64解碼）及支付寶公鑰驗(yàn)證簽名。

第五步：在步驟四驗(yàn)證簽名正確后，必須再嚴(yán)格按照如下描述校驗(yàn)通知數(shù)據(jù)的正確性。

1. 商戶需要驗(yàn)證該通知數(shù)據(jù)中的out_trade_no是否為商戶系統(tǒng)中創(chuàng)建的訂單號(hào)，
2. 判斷total_amount是否確實(shí)為該訂單的實(shí)際金額（即商戶訂單創(chuàng)建時(shí)的金額），
3. 校驗(yàn)通知中的seller_id（或者seller_email) 是否為out_trade_no這筆單據(jù)的對(duì)應(yīng)的操作方（有的時(shí)候，一個(gè)商戶可能有多個(gè)seller_id/seller_email），
4. 驗(yàn)證app_id是否為該商戶本身。

上述1、2、3、4有任何一個(gè)驗(yàn)證不通過，則表明本次通知是異常通知，務(wù)必忽略。在上述驗(yàn)證通過后商戶必須根據(jù)支付寶不同類型的業(yè)務(wù)通知，正確的進(jìn)行不同的業(yè)務(wù)處理，并且過濾重復(fù)的通知結(jié)果數(shù)據(jù)。在支付寶的業(yè)務(wù)通知中，只有交易通知狀態(tài)為TRADE_SUCCESS或TRADE_FINISHED時(shí)，支付寶才會(huì)認(rèn)定為買家付款成功。

驗(yàn)簽過程代碼描述【這里列舉java示例，按照服務(wù)端SDK中提供的工具類】：

Map<String, String> paramsMap = ... //將異步通知中收到的待驗(yàn)證所有參數(shù)都存放到map中
boolean signVerified = AlipaySignature.rsaCheckV1(paramsMap, ALIPAY_PUBLIC_KEY, CHARSET) //調(diào)用SDK驗(yàn)證簽名
if(signVerfied){
   // TODO 驗(yàn)簽成功后
   //按照支付結(jié)果異步通知中的描述，對(duì)支付結(jié)果中的業(yè)務(wù)內(nèi)容進(jìn)行1\2\3\4二次校驗(yàn)，校驗(yàn)成功后在response中返回success，校驗(yàn)失敗返回failure
}else{
    // TODO 驗(yàn)簽失敗則記錄異常日志，并在response中返回failure.
}

注意：

• 狀態(tài)TRADE_SUCCESS的通知觸發(fā)條件是商戶簽約的產(chǎn)品支持退款功能的前提下，買家付款成功；
• 交易狀態(tài)TRADE_FINISHED的通知觸發(fā)條件是商戶簽約的產(chǎn)品不支持退款功能的前提下，買家付款成功；或者，商戶簽約的產(chǎn)品支持退款功能的前提下，交易已經(jīng)成功并且已經(jīng)超過可退款期限。