上海翻譯公司完成即時到賬退款接口文檔說明中文翻譯

1  文檔說明 

1.1  文檔說明 

本文檔是《即時到賬批量退款有密接口(refund_fastpay_by_platform_pwd)》附錄文檔，它詳細解釋了在技術接入與使用過程中需要注意的地方，以幫助商戶避免風險產(chǎn)生。 

 

閱讀后如有疑問，請聯(lián)系支付寶相關技術支持。 

1.2  業(yè)務術語 

表1-1 業(yè)務術語

 

術語  解釋 

請求  通過HTTP協(xié)議把需要傳輸?shù)臄?shù)據(jù)發(fā)送給接收方的過程。 

返回  支付寶根據(jù)得到的數(shù)據(jù)處理完成后，支付寶將處理完成的結果信息反饋給商戶網(wǎng)站。 

敏感詞  帶有敏感政治傾向、暴力傾向、不健康色彩或不文明的詞。 

特殊字符  在detail_data的格式中用來作分割符，特殊字符包括：“^”、“|”、“$”、“#”。 

 

 

2  責任歸屬 

文檔中所涉及到的規(guī)則都是根據(jù)在接入與使用支付寶接口的過程中出現(xiàn)的一些主要風險而做的防范措施，請商戶予以關注。請在接入及使用支付寶接口的過程中，嚴格依照支付寶提供的接口技術文檔（即時到賬批量退款有密接口(refund_fastpay_by_platform_pwd).pdf）、代碼示例、本文檔（即時到賬批量退款有密接口(refund_fastpay_by_platform_pwd)接入與使用規(guī)則）等接口資料，否則由此導致的風險以及資金損失或者擴大情形需商戶自行承擔。

3 技術接入規(guī)則 

表3-1 技術接入規(guī)則

類型  細則 原因 

賬號  配置的合作者身份ID與安全校驗碼key必須保證與簽約信息匹配  防止接口無法正常使用或出現(xiàn)資金損失 

必須保護合作者身份ID與安全校驗碼key的隱私性 防止簽約的賬號信息被盜用，導致資金受損、被他人惡意利用等。

安全  支付寶的通知IP是121.0.26.1與121.0.26.2。該IP地址不是商戶訪問支付寶的地址，而是支付寶發(fā)送通知給商戶的出口地址。  如果商戶網(wǎng)站設置了IP白名單（即IP過濾），需要把支付寶的通知IP地址加入白名單中 

商戶必須以DNS解析的方式訪問支付寶接口，不要設置DNS cache，不要綁定支付寶IP。如果為了商戶自身安全必須綁定支付寶IP時，必須向支付寶的技術支持人員備案。  支付寶IP地址一旦變更，會導致商戶無法請求或訪問支付寶，致使商戶業(yè)務直接不可用。 

簽名  請求的所有參數(shù)，需要根據(jù)參數(shù)名=參數(shù)值的格式，按首字符字典順序（ascii值大�。┡判�，若遇到相同首字符，則判斷第二個字符，以此類推，待簽名字符串需要以“參數(shù)名1=參數(shù)值1&參數(shù)名2=參數(shù)值2&….&參數(shù)名N=參數(shù)值N”的規(guī)則進行拼接。  避免接口無法正常使用 

在對請求的參數(shù)做簽名時，這些參數(shù)必須來源于請求參數(shù)列表，并且除去列表中的參數(shù)sign、sign_type。  避免接口無法正常使用 

在對請求的參數(shù)做簽名時，對于請求參數(shù)列表中那些可空的參數(shù)，如果選擇使用它們，那么這些參數(shù)的參數(shù)值必須不能為空或空值。  避免接口無法正常使用 

簽名時將字符轉(zhuǎn)化成字節(jié)流時指定的字符集與_input_charset保持一致；如果傳遞了_input_charset參數(shù)，這個參數(shù)也應該包含在待簽名數(shù)據(jù)中。  避免接口報錯ILLEGAL_SIGN 

待簽名數(shù)據(jù)應該是參數(shù)原始值而不是url encoding之后的值，例如：調(diào)用某接口需要對請求參數(shù)email進行數(shù)字簽名，那么待簽名數(shù)據(jù)應該是[email protected]，而不是email=test%40msn.com。 避免接口報錯ILLEGAL_SIGN 

參數(shù)配置  在請求參數(shù)列表中，不可空的參數(shù)必須配置。  避免接口無法正常使用 

在請求參數(shù)列表中，可空的但需要多選一的多個參數(shù)中，必須配置至少一個。  避免接口無法正常使用 

必須按照請求參數(shù)列表中各參數(shù)的格式要求配置  避免接口無法正常使用 

必須設置請求參數(shù)_input_charset（編碼格式），即該參數(shù)不能為空，并讓該參數(shù)加入簽名運算。  避免接口無法正常使用 

退款理由中不能包含“^”、“|”、“$”、“#”等影響detail_data格式的特殊字符。  避免接口無法正常使用 

集成該接口時，退款批次號batch_no的格式必須是提交的當天日期+隨機數(shù)。  業(yè)務規(guī)則要求 

無退分潤數(shù)據(jù)集格式  不支持退分潤功能 

接口構造  必須使用支付寶的網(wǎng)關發(fā)送請求信息給支付寶，請求網(wǎng)關：https://mapi.alipay.com/gateway.do。 

避免被釣魚網(wǎng)站利用 

發(fā)送給支付寶的請求，請求參數(shù)不僅包含參與簽名的參數(shù)，還包含參數(shù)sign、sign_type。  避免接口無法正常使用 

發(fā)送給支付寶的請求，如果使用form表單傳輸，需要按照以下要求編寫： 

 action的值必須為“https://mapi.alipay.com/gateway.do?_input_charset=該值”，如：https://mapi.alipay.com/gateway.do?_input_charset=utf-8。 不允許寫成完整的請求鏈接地址，即禁止https://mapi.alipay.com/gateway.do?后帶有所有要請求給支付寶的請求參數(shù)數(shù)據(jù)； 

 <form>與</form>之間需包含所有要請求給支付寶的參數(shù)，且每個參數(shù)的格式為<input type="hidden" name="參數(shù)名" value="參數(shù)值" />； 

 在眾多請求參數(shù)中，請求參數(shù)_input_charset（編碼格式）必須存在于form表單中，即form表單中必須含有<input type="hidden" name="_input_charset" value="參數(shù)值">； 

 <form>與</form>之間包含的數(shù)據(jù)只允許是要請求給支付寶的參數(shù)，禁止出現(xiàn)商戶自行命名，不在接口技術文檔請求參數(shù)列表中的其他數(shù)據(jù)； 

 form表單的method屬性，可自行選擇get、post兩種。 

 

 避免請求支付寶時報錯，錯誤碼為ILLEGAL_SIGN； 

 在win7系統(tǒng)下，如果瀏覽器是IE8以上，有可能出現(xiàn)發(fā)送請求鏈接時會無法跳轉(zhuǎn)到支付寶，當前頁面為空白頁的情況。 

 

數(shù)據(jù)傳輸  必須使用https協(xié)議，支持get或post方式提交。  避免接口無法正常使用 

通知返回驗證  如果有設置通知路徑及觸發(fā)條件，則必須使用獲取到的參數(shù)notify_id再次請求支付寶，獲取是否是支付寶發(fā)送的驗證結果。該請求鏈接是： 

https://mapi.alipay.com/gateway.do?partner=合作者身份ID&notify_id=通知ID的值  驗證是否是支付寶發(fā)來的請求 

在對通知的參數(shù)做簽名時，這些參數(shù)必須來源于支付寶通知回來的參數(shù)，并且除去列表中的參數(shù)sign、sign_type，根據(jù)參數(shù)名=參數(shù)值的格式，按首字符字典順序（ascii值大小）排序，若遇到相同首字符，則判斷第二個字符，以此類推，待簽名字符串需要以“參數(shù)名1=參數(shù)值1&參數(shù)名2=參數(shù)值2&….&參數(shù)名N=參數(shù)值N”的規(guī)則進行拼接，得到的簽名結果與獲取到的參數(shù)sign值做比較。  驗證返回的簽名 

返回數(shù)據(jù)處理  在返回參數(shù)中，“退款成功總數(shù)（success_num）”參數(shù)值說明一個退款批次中退款成功的總筆數(shù)。  避免商戶獲取狀態(tài)失敗導致業(yè)務線的退款全部失敗 

退款成功后，除了本接口的異步通知結果返回，還有即時到賬接口也會被觸發(fā)發(fā)送交易退款狀態(tài)通知給商戶。  商戶要做好業(yè)務邏輯判斷，以免造成多退款的資損。 

本接口直接返回的XML信息（T/F）僅代表提交成功與否，不代表退款成功或者失敗，商戶必須根據(jù)退款異步通知中的結果集來判斷是否退款成功。  避免由于商戶余額不足等問題導致接口提交退款失敗使用戶投訴 

支付寶主動發(fā)送通知，當商戶接收到通知數(shù)據(jù)后必須給支付寶返回“success”字符串，不允許返回其他多余字符。  如果商戶返回給支付寶的信息不是“success”，支付寶最多重復發(fā)送8次通知。 

必須保證設置的通知路徑互聯(lián)網(wǎng)上能訪問得到，且訪問順暢。  避免接收不到支付寶發(fā)送的通知 

必須對返回的數(shù)據(jù)進行處理  以便商戶能夠了解接口的使用情況，以及進行商戶的后續(xù)業(yè)務操作。 

必須判斷退款操作以后的業(yè)務邏輯處理程序是否有重復執(zhí)行  防止出現(xiàn)商戶的業(yè)務操作被重復執(zhí)行，導致出現(xiàn)資金損失，如重復充值、重復付款等。 

建議每一次退款操作需以日志形式記錄到商戶網(wǎng)站的日志操作數(shù)據(jù)庫中  用來在必要時檢查或跟蹤業(yè)務處理情況 

接入環(huán)境  不能把接口嵌入iframe框架中  避免接口無法正常使用 

錯誤碼處理  遇到特殊錯誤碼（如：UNKNOWN_EXCEPTION、GENERIC_FAILURE、SYSTEM_ERROR），須暫停后續(xù)操作，或者聯(lián)系支付寶技術支持協(xié)助處理。 

HTML方式返回或異步通知方式返回。  一般這種情況有可能請求已經(jīng)提交到支付寶，支付寶系統(tǒng)失去響應但有可能由恢復機制自動回復并提交請求。 

出現(xiàn)“REFUND_DATE_ERROR”表示退款時間錯誤，請修改退款時間重新提交請求。 

HTML方式返回。  出現(xiàn)這種情況可能原因： 

 退款時間為空或格式不符合yyyy-MM-dd HH:mm:ss； 

 退款日期與退款批次號中的日期不一致。 

 

出現(xiàn)“TRADE_STATUS_ERROR”表示在該交易狀態(tài)下不允許退款。 

HTML方式返回。  可能原因：因交易一方賬號被鎖定，導致交易處于掛起狀態(tài)而不能退款。 

出現(xiàn)“REFUND_FAIL”表示退款失敗，請聯(lián)系支付寶技術支持協(xié)助處理。 

異步通知方式返回。  該結果碼只會出現(xiàn)在做意外數(shù)據(jù)恢復時，找不到結果碼的情況。 

出現(xiàn)“RESULT_AMOUNT_NOT_VALID”表示退款金額不合理，請重新檢查退款金額。 

異步通知方式返回。  可能原因：一般是交易金額大于退款金額，如退款的票面價、機建費、燃油費、航意險大于交易時的相關金額。 

出現(xiàn)“REFUND_TRADE_FEE_ERROR”表示交易退款金額與付款金額不一致，請更新交易退款金額。 

異步通知方式返回。  出現(xiàn)原因是退款金額與付款金額不一致 

出現(xiàn)“BATCH_REFUND_LOCK_ERROR”表示同一時間不允許進行多筆并發(fā)退款。 

異步通知方式返回。  同一時間不允許進行多筆并發(fā)退款 

遇到如下錯誤碼時，系統(tǒng)會啟動重試機制： 

 TRADE_PAYMENT_ERROR 

 TRADE_PROCESS_ERROR 

 QUERY_PARTICIPANT_ERROR 

 

商戶無需處理。  支付寶系統(tǒng)內(nèi)部錯誤，可以由支付寶內(nèi)部自行解決 

自主編寫接口代碼規(guī)則  如果不使用支付寶提供的代碼示例來集成接口，那么必須根據(jù)技術文檔中簽名機制和通知返回數(shù)據(jù)處理章節(jié)及本文檔的技術接入規(guī)則、接口使用規(guī)則、測試流程規(guī)則，來編寫符合商戶網(wǎng)站項目的接口代碼。  避免接口無法正常使用 

 

 

4  接口使用規(guī)則 

表4-1 接口使用規(guī)則

 

 

類型 

規(guī)范點 

原因 

網(wǎng)絡  確保網(wǎng)絡順暢  防止接口調(diào)用失敗 

業(yè)務操作規(guī)則  接口支持重復調(diào)用，但必須確保每個合作伙伴每個退款批次號（batch_no）的唯一性。  防止重復退款 

同一批明細里（detail_data）不允許包含兩條交易號相同的退款明細  防止重復退款 

必須保證要退款的賬號余額充足  避免退款不成功 

要退款的交易號必須存在且已經(jīng)是付款成功狀態(tài)，即交易狀態(tài)（TRADE_STATUS）是TRADE_SUCCESS的狀態(tài)。  避免退款不成功 

收款賬號不是簽約賬號，即參數(shù)seller_email填寫的支付寶賬號對應的合作者身份ID不是參數(shù)partner對應的合作者身份ID，該seller_email填寫的支付寶賬號必須與平臺或者退款接口使用商戶簽約支付圈接口。  否則退款時會報沒有簽約的錯誤，即“PARTNER_NOT_SIGN_PROTOCOL”。 

如果請求支付寶以后IS_SUCCESS返回T，那么當該批次中有一個或多個交易退款失敗，此時不影響整個批次中其他交易的退款。 

 如果請求支付寶以后IS_SUCCESS返回為F，那么該筆批次的所有交易退款都失�。� 

 如果請求支付寶以后IS_SUCCESS返回為T，該筆批次中的各個交易彼此獨立，所以失敗的交易退款不會影響成功的交易退款。 

 

如果接口中設置了notify_url，當請求支付寶以后IS_SUCCESS返回為F時，支付寶系統(tǒng)不會發(fā)送服務器異步通知。  對請求的校驗未通過 

余額支付功能關閉的情況下，接口退款不受影響。  保證商戶順利完成交易退款 

該接口支持單筆和批量退款，批量退款最多一次支持1000筆，50筆是最高效的退款筆數(shù)。數(shù)據(jù)請求以表單POST方式發(fā)送到支付寶。  無法傳遞大量數(shù)據(jù) 

一筆交易可以多次退款，只需要遵守多次退款的總金額不超過該筆交易付款金額的原則。  支持多次退款 

一筆交易的退款次數(shù)上限為99次  超過該次數(shù)則支付寶系統(tǒng)不會處理該筆交易的退款，如果接口中設置了notify_url，那么支付寶系統(tǒng)也不會發(fā)送服務器異步通知。 

需要對退款成功后的異步通知返回結果做所有返回參數(shù)的解析分類，判斷交易狀態(tài)即可。  防止未來業(yè)務變更，有更好的兼容性。 

操作退款時需要安裝數(shù)字證書或支付盾等其他安全產(chǎn)品。  有密退款時需要輸入支付密碼 

單筆數(shù)據(jù)集規(guī)則  退款筆數(shù)總和要等于參數(shù)batch_num的值  數(shù)據(jù)一致，防止發(fā)生退款金額錯誤。 

退款資金流向  客戶銀行卡掛失或者注銷將無法退回到客戶賬戶中。需要商戶向客戶收集新的銀行卡號并且提供聲明對新的銀行卡號正確性負責，委托支付寶退款。  退回到卡的情況：信用卡、信用卡卡通、Q賬號、支付寶中間賬號（例如：[email protected]）支付的訂單；其他的實時到賬退到支付寶余額賬戶。 

接口異常  異步處理如果響應時間過長直接導致退款返回失敗，或者退款通知超過24小時未發(fā)出，則可以人工進行重新提交請求。  可能是支付寶的消息積壓導致異步調(diào)度任務失敗 

 

 

5  測試流程規(guī)則 

表5-1 測試流程規(guī)則

 

 

步驟 

調(diào)試內(nèi)容 

備注 

Windows環(huán)境（linux環(huán)境）服務器配置要求： 

推薦配置Java 1.6以上運行環(huán)境，符合servlet2.4規(guī)范的WEB容器。 

第一步：在本機單獨對這個接口進行調(diào)試。 

 根據(jù)接口要求配置批量退款請求參數(shù)，發(fā)送請求數(shù)據(jù) 

 返回批量退款處理結果數(shù)據(jù) 

僅僅把接口配置好，不要放在商戶的網(wǎng)站項目中。 

第二步：在服務器上單獨對這個而接口進行調(diào)試 

 根據(jù)接口要求配置批量退款請求參數(shù)，發(fā)送請求數(shù)據(jù) 

 返回批量退款處理結果數(shù)據(jù) 

本機調(diào)試沒有問題后，再放入服務器中調(diào)試。 

第三步：接口融合到網(wǎng)站項目中 

 根據(jù)接口要求配置批量退款請求參數(shù)，發(fā)送請求數(shù)據(jù) 

 返回批量退款處理結果數(shù)據(jù) 

 對獲取的返回結果數(shù)據(jù)進行處理 

把調(diào)試好的接口與商戶網(wǎng)站項目的業(yè)務流程進行銜接和融合。 

第四步：在本機對融合后的網(wǎng)站項目進行調(diào)試 

 整個業(yè)務操作流程 

 根據(jù)接口要求配置批量退款請求參數(shù)，發(fā)送請求數(shù)據(jù) 

 返回批量退款處理結果數(shù)據(jù) 

 對獲取的返回結果數(shù)據(jù)進行處理 

 業(yè)務后續(xù)的執(zhí)行 

在本機調(diào)試銜接到網(wǎng)站項目后的接口。 

第五步：在服務器對融合后的網(wǎng)站項目進行調(diào)試 

 整個業(yè)務操作流程 

 根據(jù)接口要求配置批量退款請求參數(shù)，發(fā)送請求數(shù)據(jù) 

 返回批量退款處理結果數(shù)據(jù) 

 對獲取的返回結果數(shù)據(jù)進行處理 

 業(yè)務后續(xù)的執(zhí)行 

本機調(diào)試沒有問題后，再放入服務器中調(diào)試。