世聯(lián)翻譯公司完成即時(shí)到賬退款接口文檔說明中文翻譯

1  文檔說明 

1.1  文檔說明 

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

 

閱讀后如有疑問，請(qǐng)聯(lián)系支付寶相關(guān)技術(shù)支持。 

1.2  業(yè)務(wù)術(shù)語 

表1-1 業(yè)務(wù)術(shù)語

 

術(shù)語  解釋 

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

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

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

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

 

 

2  責(zé)任歸屬 

文檔中所涉及到的規(guī)則都是根據(jù)在接入與使用支付寶接口的過程中出現(xiàn)的一些主要風(fēng)險(xiǎn)而做的防范措施，請(qǐng)商戶予以關(guān)注。請(qǐng)?jiān)诮尤爰笆褂弥Ц秾毥涌诘倪^程中，嚴(yán)格依照支付寶提供的接口技術(shù)文檔（即時(shí)到賬批量退款有密接口(refund_fastpay_by_platform_pwd).pdf）、代碼示例、本文檔（即時(shí)到賬批量退款有密接口(refund_fastpay_by_platform_pwd)接入與使用規(guī)則）等接口資料，否則由此導(dǎo)致的風(fēng)險(xiǎn)以及資金損失或者擴(kuò)大情形需商戶自行承擔(dān)。

3 技術(shù)接入規(guī)則 

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

類型  細(xì)則 原因 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

 

 避免請(qǐng)求支付寶時(shí)報(bào)錯(cuò)，錯(cuò)誤碼為ILLEGAL_SIGN； 

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

 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

 退款日期與退款批次號(hào)中的日期不一致。 

 

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

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

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

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

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

異步通知方式返回。  可能原因：一般是交易金額大于退款金額，如退款的票面價(jià)、機(jī)建費(fèi)、燃油費(fèi)、航意險(xiǎn)大于交易時(shí)的相關(guān)金額。 

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

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

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

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

遇到如下錯(cuò)誤碼時(shí)，系統(tǒng)會(huì)啟動(dòng)重試機(jī)制： 

 TRADE_PAYMENT_ERROR 

 TRADE_PROCESS_ERROR 

 QUERY_PARTICIPANT_ERROR 

 

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

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

 

 

4  接口使用規(guī)則 

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

 

 

類型 

規(guī)范點(diǎn) 

原因 

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

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

同一批明細(xì)里（detail_data）不允許包含兩條交易號(hào)相同的退款明細(xì)  防止重復(fù)退款 

必須保證要退款的賬號(hào)余額充足  避免退款不成功 

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

收款賬號(hào)不是簽約賬號(hào)，即參數(shù)seller_email填寫的支付寶賬號(hào)對(duì)應(yīng)的合作者身份ID不是參數(shù)partner對(duì)應(yīng)的合作者身份ID，該seller_email填寫的支付寶賬號(hào)必須與平臺(tái)或者退款接口使用商戶簽約支付圈接口。  否則退款時(shí)會(huì)報(bào)沒有簽約的錯(cuò)誤，即“PARTNER_NOT_SIGN_PROTOCOL”。 

如果請(qǐng)求支付寶以后IS_SUCCESS返回T，那么當(dāng)該批次中有一個(gè)或多個(gè)交易退款失敗，此時(shí)不影響整個(gè)批次中其他交易的退款。 

 如果請(qǐng)求支付寶以后IS_SUCCESS返回為F，那么該筆批次的所有交易退款都失敗； 

 如果請(qǐng)求支付寶以后IS_SUCCESS返回為T，該筆批次中的各個(gè)交易彼此獨(dú)立，所以失敗的交易退款不會(huì)影響成功的交易退款。 

 

如果接口中設(shè)置了notify_url，當(dāng)請(qǐng)求支付寶以后IS_SUCCESS返回為F時(shí)，支付寶系統(tǒng)不會(huì)發(fā)送服務(wù)器異步通知。  對(duì)請(qǐng)求的校驗(yàn)未通過 

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

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

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

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

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

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

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

退款資金流向  客戶銀行卡掛失或者注銷將無法退回到客戶賬戶中。需要商戶向客戶收集新的銀行卡號(hào)并且提供聲明對(duì)新的銀行卡號(hào)正確性負(fù)責(zé)，委托支付寶退款。  退回到卡的情況：信用卡、信用卡卡通、Q賬號(hào)、支付寶中間賬號(hào)（例如：0571-88158090@alipay.com）支付的訂單；其他的實(shí)時(shí)到賬退到支付寶余額賬戶。 

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

 

 

5  測(cè)試流程規(guī)則 

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

步驟 

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

備注 

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

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

第一步：在本機(jī)單獨(dú)對(duì)這個(gè)接口進(jìn)行調(diào)試。 

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

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

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

第二步：在服務(wù)器上單獨(dú)對(duì)這個(gè)而接口進(jìn)行調(diào)試 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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