- 行業(yè)新聞
-
上海翻譯公司完成即時到賬退款接口文檔說明中文翻譯
發(fā)布時間：2018-11-14 09:36 點擊：
上海翻譯公司完成即時到賬退款接口文檔說明中文翻譯
1 文檔說明1.1 文檔說明本文檔是《即時到賬批量退款有密接口(refund_fastpay_by_platform_pwd)》附錄文檔，它詳細解釋了在技術(shù)接入與使用過程中需要注意的地方，以幫助商戶避免風險產(chǎn)生。閱讀后如有疑問，請聯(lián)系支付寶相關(guān)技術(shù)支持。1.2 業(yè)務(wù)術(shù)語表1-1 業(yè)務(wù)術(shù)語術(shù)語 解釋請求 通過HTTP協(xié)議把需要傳輸?shù)臄?shù)據(jù)發(fā)送給接收方的過程。返回 支付寶根據(jù)得到的數(shù)據(jù)處理完成后，支付寶將處理完成的結(jié)果信息反饋給商戶網(wǎng)站。敏感詞 帶有敏感政治傾向、暴力傾向、不健康色彩或不文明的詞。特殊字符 在detail_data的格式中用來作分割符，特殊字符包括：“^”、“|”、“$”、“#”。2 責任歸屬文檔中所涉及到的規(guī)則都是根據(jù)在接入與使用支付寶接口的過程中出現(xiàn)的一些主要風險而做的防范措施，請商戶予以關(guān)注。請在接入及使用支付寶接口的過程中，嚴格依照支付寶提供的接口技術(shù)文檔（即時到賬批量退款有密接口(refund_fastpay_by_platform_pwd).pdf）、代碼示例、本文檔（即時到賬批量退款有密接口(refund_fastpay_by_platform_pwd)接入與使用規(guī)則）等接口資料，否則由此導(dǎo)致的風險以及資金損失或者擴大情形需商戶自行承擔。3 技術(shù)接入規(guī)則表3-1 技術(shù)接入規(guī)則類型 細則 原因賬號 配置的合作者身份ID與安全校驗碼key必須保證與簽約信息匹配 防止接口無法正常使用或出現(xiàn)資金損失必須保護合作者身份ID與安全校驗碼key的隱私性 防止簽約的賬號信息被盜用，導(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ù)支持人員備案。 支付寶IP地址一旦變更，會導(dǎo)致商戶無法請求或訪問支付寶，致使商戶業(yè)務(wù)直接不可用。簽名 請求的所有參數(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ù)也應(yīng)該包含在待簽名數(shù)據(jù)中。 避免接口報錯ILLEGAL_SIGN待簽名數(shù)據(jù)應(yīng)該是參數(shù)原始值而不是url encoding之后的值，例如：調(diào)用某接口需要對請求參數(shù)email進行數(shù)字簽名，那么待簽名數(shù)據(jù)應(yīng)該是[email protected]，而不是email=test%40msn.com。 避免接口報錯ILLEGAL_SIGN參數(shù)配置 在請求參數(shù)列表中，不可空的參數(shù)必須配置。 避免接口無法正常使用在請求參數(shù)列表中，可空的但需要多選一的多個參數(shù)中，必須配置至少一個。 避免接口無法正常使用必須按照請求參數(shù)列表中各參數(shù)的格式要求配置 避免接口無法正常使用必須設(shè)置請求參數(shù)_input_charset（編碼格式），即該參數(shù)不能為空，并讓該參數(shù)加入簽名運算。 避免接口無法正常使用退款理由中不能包含“^”、“|”、“$”、“#”等影響detail_data格式的特殊字符。 避免接口無法正常使用集成該接口時，退款批次號batch_no的格式必須是提交的當天日期+隨機數(shù)。 業(yè)務(wù)規(guī)則要求無退分潤數(shù)據(jù)集格式 不支持退分潤功能接口構(gòu)造 必須使用支付寶的網(wǎng)關(guān)發(fā)送請求信息給支付寶，請求網(wǎng)關(guān)：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ù)列表中的其他數(shù)據(jù)； form表單的method屬性，可自行選擇get、post兩種。 避免請求支付寶時報錯，錯誤碼為ILLEGAL_SIGN； 在win7系統(tǒng)下，如果瀏覽器是IE8以上，有可能出現(xiàn)發(fā)送請求鏈接時會無法跳轉(zhuǎn)到支付寶，當前頁面為空白頁的情況。數(shù)據(jù)傳輸 必須使用https協(xié)議，支持get或post方式提交。 避免接口無法正常使用通知返回驗證 如果有設(shè)置通知路徑及觸發(fā)條件，則必須使用獲取到的參數(shù)notify_id再次請求支付寶，獲取是否是支付寶發(fā)送的驗證結(jié)果。該請求鏈接是：https://mapi.alipay.com/gateway.do?partner=合作者身份ID¬ify_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ī)則進行拼接，得到的簽名結(jié)果與獲取到的參數(shù)sign值做比較。 驗證返回的簽名返回數(shù)據(jù)處理 在返回參數(shù)中，“退款成功總數(shù)（success_num）”參數(shù)值說明一個退款批次中退款成功的總筆數(shù)。 避免商戶獲取狀態(tài)失敗導(dǎo)致業(yè)務(wù)線的退款全部失敗退款成功后，除了本接口的異步通知結(jié)果返回，還有即時到賬接口也會被觸發(fā)發(fā)送交易退款狀態(tài)通知給商戶。 商戶要做好業(yè)務(wù)邏輯判斷，以免造成多退款的資損。本接口直接返回的XML信息（T/F）僅代表提交成功與否，不代表退款成功或者失敗，商戶必須根據(jù)退款異步通知中的結(jié)果集來判斷是否退款成功。 避免由于商戶余額不足等問題導(dǎo)致接口提交退款失敗使用戶投訴支付寶主動發(fā)送通知，當商戶接收到通知數(shù)據(jù)后必須給支付寶返回“success”字符串，不允許返回其他多余字符。 如果商戶返回給支付寶的信息不是“success”，支付寶最多重復(fù)發(fā)送8次通知。必須保證設(shè)置的通知路徑互聯(lián)網(wǎng)上能訪問得到，且訪問順暢。 避免接收不到支付寶發(fā)送的通知必須對返回的數(shù)據(jù)進行處理 以便商戶能夠了解接口的使用情況，以及進行商戶的后續(xù)業(yè)務(wù)操作。必須判斷退款操作以后的業(yè)務(wù)邏輯處理程序是否有重復(fù)執(zhí)行 防止出現(xiàn)商戶的業(yè)務(wù)操作被重復(fù)執(zhí)行，導(dǎo)致出現(xiàn)資金損失，如重復(fù)充值、重復(fù)付款等。建議每一次退款操作需以日志形式記錄到商戶網(wǎng)站的日志操作數(shù)據(jù)庫中 用來在必要時檢查或跟蹤業(yè)務(wù)處理情況接入環(huán)境 不能把接口嵌入iframe框架中 避免接口無法正常使用錯誤碼處理 遇到特殊錯誤碼（如：UNKNOWN_EXCEPTION、GENERIC_FAILURE、SYSTEM_ERROR），須暫停后續(xù)操作，或者聯(lián)系支付寶技術(shù)支持協(xié)助處理。HTML方式返回或異步通知方式返回。 一般這種情況有可能請求已經(jīng)提交到支付寶，支付寶系統(tǒng)失去響應(yīng)但有可能由恢復(fù)機制自動回復(fù)并提交請求。出現(xiàn)“REFUND_DATE_ERROR”表示退款時間錯誤，請修改退款時間重新提交請求。HTML方式返回。 出現(xiàn)這種情況可能原因： 退款時間為空或格式不符合yyyy-MM-dd HH:mm:ss； 退款日期與退款批次號中的日期不一致。出現(xiàn)“TRADE_STATUS_ERROR”表示在該交易狀態(tài)下不允許退款。HTML方式返回。 可能原因：因交易一方賬號被鎖定，導(dǎo)致交易處于掛起狀態(tài)而不能退款。出現(xiàn)“REFUND_FAIL”表示退款失敗，請聯(lián)系支付寶技術(shù)支持協(xié)助處理。異步通知方式返回。 該結(jié)果碼只會出現(xiàn)在做意外數(shù)據(jù)恢復(fù)時，找不到結(jié)果碼的情況。出現(xiàn)“RESULT_AMOUNT_NOT_VALID”表示退款金額不合理，請重新檢查退款金額。異步通知方式返回。 可能原因：一般是交易金額大于退款金額，如退款的票面價、機建費、燃油費、航意險大于交易時的相關(guān)金額。出現(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ù)文檔中簽名機制和通知返回數(shù)據(jù)處理章節(jié)及本文檔的技術(shù)接入規(guī)則、接口使用規(guī)則、測試流程規(guī)則，來編寫符合商戶網(wǎng)站項目的接口代碼。 避免接口無法正常使用4 接口使用規(guī)則表4-1 接口使用規(guī)則類型規(guī)范點原因網(wǎng)絡(luò) 確保網(wǎng)絡(luò)順暢 防止接口調(diào)用失敗業(yè)務(wù)操作規(guī)則 接口支持重復(fù)調(diào)用，但必須確保每個合作伙伴每個退款批次號（batch_no）的唯一性。 防止重復(fù)退款同一批明細里（detail_data）不允許包含兩條交易號相同的退款明細 防止重復(fù)退款必須保證要退款的賬號余額充足 避免退款不成功要退款的交易號必須存在且已經(jīng)是付款成功狀態(tài)，即交易狀態(tài)（TRADE_STATUS）是TRADE_SUCCESS的狀態(tài)。 避免退款不成功收款賬號不是簽約賬號，即參數(shù)seller_email填寫的支付寶賬號對應(yīng)的合作者身份ID不是參數(shù)partner對應(yīng)的合作者身份ID，該seller_email填寫的支付寶賬號必須與平臺或者退款接口使用商戶簽約支付圈接口。 否則退款時會報沒有簽約的錯誤，即“PARTNER_NOT_SIGN_PROTOCOL”。如果請求支付寶以后IS_SUCCESS返回T，那么當該批次中有一個或多個交易退款失敗，此時不影響整個批次中其他交易的退款。 如果請求支付寶以后IS_SUCCESS返回為F，那么該筆批次的所有交易退款都失��； 如果請求支付寶以后IS_SUCCESS返回為T，該筆批次中的各個交易彼此獨立，所以失敗的交易退款不會影響成功的交易退款。如果接口中設(shè)置了notify_url，當請求支付寶以后IS_SUCCESS返回為F時，支付寶系統(tǒng)不會發(fā)送服務(wù)器異步通知。 對請求的校驗未通過余額支付功能關(guān)閉的情況下，接口退款不受影響。 保證商戶順利完成交易退款該接口支持單筆和批量退款，批量退款最多一次支持1000筆，50筆是最高效的退款筆數(shù)。數(shù)據(jù)請求以表單POST方式發(fā)送到支付寶。 無法傳遞大量數(shù)據(jù)一筆交易可以多次退款，只需要遵守多次退款的總金額不超過該筆交易付款金額的原則。 支持多次退款一筆交易的退款次數(shù)上限為99次 超過該次數(shù)則支付寶系統(tǒng)不會處理該筆交易的退款，如果接口中設(shè)置了notify_url，那么支付寶系統(tǒng)也不會發(fā)送服務(wù)器異步通知。需要對退款成功后的異步通知返回結(jié)果做所有返回參數(shù)的解析分類，判斷交易狀態(tài)即可。 防止未來業(yè)務(wù)變更，有更好的兼容性。操作退款時需要安裝數(shù)字證書或支付盾等其他安全產(chǎn)品。 有密退款時需要輸入支付密碼單筆數(shù)據(jù)集規(guī)則 退款筆數(shù)總和要等于參數(shù)batch_num的值 數(shù)據(jù)一致，防止發(fā)生退款金額錯誤。退款資金流向 客戶銀行卡掛失或者注銷將無法退回到客戶賬戶中。需要商戶向客戶收集新的銀行卡號并且提供聲明對新的銀行卡號正確性負責，委托支付寶退款。 退回到卡的情況：信用卡、信用卡卡通、Q賬號、支付寶中間賬號（例如：[email protected]）支付的訂單；其他的實時到賬退到支付寶余額賬戶。接口異常 異步處理如果響應(yīng)時間過長直接導(dǎo)致退款返回失敗，或者退款通知超過24小時未發(fā)出，則可以人工進行重新提交請求。 可能是支付寶的消息積壓導(dǎo)致異步調(diào)度任務(wù)失敗5 測試流程規(guī)則表5-1 測試流程規(guī)則步驟調(diào)試內(nèi)容備注Windows環(huán)境（linux環(huán)境）服務(wù)器配置要求：推薦配置Java 1.6以上運行環(huán)境，符合servlet2.4規(guī)范的WEB容器。第一步：在本機單獨對這個接口進行調(diào)試。 根據(jù)接口要求配置批量退款請求參數(shù)，發(fā)送請求數(shù)據(jù) 返回批量退款處理結(jié)果數(shù)據(jù)僅僅把接口配置好，不要放在商戶的網(wǎng)站項目中。第二步：在服務(wù)器上單獨對這個而接口進行調(diào)試 根據(jù)接口要求配置批量退款請求參數(shù)，發(fā)送請求數(shù)據(jù) 返回批量退款處理結(jié)果數(shù)據(jù)本機調(diào)試沒有問題后，再放入服務(wù)器中調(diào)試。第三步：接口融合到網(wǎng)站項目中 根據(jù)接口要求配置批量退款請求參數(shù)，發(fā)送請求數(shù)據(jù) 返回批量退款處理結(jié)果數(shù)據(jù) 對獲取的返回結(jié)果數(shù)據(jù)進行處理把調(diào)試好的接口與商戶網(wǎng)站項目的業(yè)務(wù)流程進行銜接和融合。第四步：在本機對融合后的網(wǎng)站項目進行調(diào)試 整個業(yè)務(wù)操作流程 根據(jù)接口要求配置批量退款請求參數(shù)，發(fā)送請求數(shù)據(jù) 返回批量退款處理結(jié)果數(shù)據(jù) 對獲取的返回結(jié)果數(shù)據(jù)進行處理 業(yè)務(wù)后續(xù)的執(zhí)行在本機調(diào)試銜接到網(wǎng)站項目后的接口。第五步：在服務(wù)器對融合后的網(wǎng)站項目進行調(diào)試 整個業(yè)務(wù)操作流程 根據(jù)接口要求配置批量退款請求參數(shù)，發(fā)送請求數(shù)據(jù) 返回批量退款處理結(jié)果數(shù)據(jù) 對獲取的返回結(jié)果數(shù)據(jù)進行處理 業(yè)務(wù)后續(xù)的執(zhí)行本機調(diào)試沒有問題后，再放入服務(wù)器中調(diào)試。世聯(lián)翻譯-讓世界自由溝通！專業(yè)的全球語言翻譯供應(yīng)商，上海翻譯公司專業(yè)品牌。絲路沿線56種語言一站式翻譯與技術(shù)解決方案，專業(yè)英語翻譯、日語翻譯等文檔翻譯、同傳口譯、視頻翻譯、出國外派服務(wù)，加速您的全球交付。 世聯(lián)翻譯公司在北京、上海、深圳等國際交往城市設(shè)有翻譯基地，業(yè)務(wù)覆蓋全國城市。每天有近百萬字節(jié)的信息和貿(mào)易通過世聯(lián)走向全球！積累了大量政商用戶數(shù)據(jù)，翻譯人才庫數(shù)據(jù)，多語種語料庫大數(shù)據(jù)。世聯(lián)品牌和服務(wù)品質(zhì)已得到政務(wù)防務(wù)和國際組織、跨國公司和大中型企業(yè)等近萬用戶的認可。
