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

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

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

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

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

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

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

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

對于iOS平臺而言返回參數(shù)是一個NSDictionary對象，對于Android平臺而言是一個map結(jié)構(gòu)體。里面有三個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é)果碼含義

同步通知驗證

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

在返回數(shù)據(jù)resultStatus為9000的情況下，解析result結(jié)果，提取驗證簽名的相關(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īng)的SHA256WithRSA簽名驗證函數(shù)，傳入簽名的原始字符串、支付寶公鑰、簽名類型RSA、簽名字符進行合法性驗證。

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

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

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

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

對于App支付產(chǎn)生的交易，支付寶會根據(jù)原始支付API中傳入的異步通知地址notify_url，通過POST請求的形式將支付結(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’]；
• 支付寶主動發(fā)起通知，該方式才會被啟用；
• 只有在支付寶的交易管理中存在該筆交易，且發(fā)生了交易狀態(tài)的改變，支付寶才會通過該方式發(fā)起服務(wù)器通知（即時到賬交易狀態(tài)為“等待買家付款”的狀態(tài)默認(rèn)是不會發(fā)送通知的）；
• 服務(wù)器間的交互，不像頁面跳轉(zhuǎn)同步通知可以在頁面上顯示出來，這種交互方式是不可見的；
• 第一次交易狀態(tài)改變（即時到賬中此時交易狀態(tài)是交易完成）時，不僅會返回同步處理結(jié)果，而且服務(wù)器異步通知頁面也會收到支付寶發(fā)來的處理結(jié)果通知；
• 程序執(zhí)行完后必須打印輸出“success”（不包含引號）。如果商戶反饋給支付寶的字符不是success這7個字符，支付寶服務(wù)器會不斷重發(fā)通知，直到超過24小時22分鐘。一般情況下，25小時以內(nèi)完成8次通知（通知的間隔頻率一般是：4m,10m,10m,1h,2h,6h,15h）；
• 程序執(zhí)行完成后，該頁面不能執(zhí)行頁面跳轉(zhuǎn)。如果執(zhí)行頁面跳轉(zhuǎn)，支付寶會收不到success字符，會被支付寶服務(wù)器判定為該頁面程序運行出現(xiàn)異常，而重發(fā)處理結(jié)果通知；
• cookies、session等在此頁面會失效，即無法獲取這些數(shù)據(jù)；
• 該方式的調(diào)試與運行必須在服務(wù)器上，即互聯(lián)網(wǎng)上能訪問；
• 該方式的作用主要防止訂單丟失，即頁面跳轉(zhuǎn)同步通知沒有處理訂單更新，它則去處理；
• 當(dāng)商戶收到服務(wù)器異步通知并打印出success時，服務(wù)器異步通知參數(shù)notify_id才會失效。也就是說在支付寶發(fā)送同一條異步通知時（包含商戶并未成功打印出success導(dǎo)致支付寶重發(fā)數(shù)次通知），服務(wù)器異步通知參數(shù)notify_id是不變的。

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

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

某商戶設(shè)置的通知地址為https://api.xx.com/receive_notify.htm，對應(yīng)接收到通知的示例如下： 注：以下示例報文僅供參考，實際返回的詳細(xì)報文請以實際返回為準(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兩個參數(shù)外，凡是通知返回回來的參數(shù)皆是待驗簽的參數(shù)。

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

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的驗簽方法，通過簽名字符串、簽名參數(shù)（經(jīng)過base64解碼）及支付寶公鑰驗證簽名。

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

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

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

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

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

注意：

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