接口設計之應答碼方案升級研究

摘要：對于支付系統，需要以接口形式提供給商戶接入。系統設計中涉及接口調用，就有應答碼，應答碼方案不同，給接入方的開發工作有很大的影響性，層級分明的應答碼方案可以給接入方和接口提供方帶來事半功倍的效果。本文從常見的應答碼方案論證演變，推出一種新的應答碼方案。

關鍵詞：接口設計;應答碼;交易結果

1.前言

本文以支付系統為背景，闡述接口應答碼設計的方案演變研究。支付系統有前臺和后臺兩種模式的接口，前臺是指通過跳轉到支付系統的頁面來采集支付要素，后臺交易是指通過后臺服務器直接發起交易，不跳轉到接口提供方的頁面處理要素采集，在接入方頁面自行采集。前臺交易只有明確成功的時候才通知接入方，失敗不發通知;后臺交易明確成功和明確失敗時都發通知;處理中都不發通知。

同時，支付系統為了提高響應，減少服務器資源占用，采用異步應答方式，即返回同步應答僅表示受理結果，異步通知才表示處理結果。另外，在實際接入過成功，接入方的系統實現是不一致的，由于開發難度等因素，要求支付系統能夠同時提供同步接口，即滿足同步返回處理結果。

接口設計處理哪些問題？請求和應答要素，應答的同步應答、異步通知要素，交易結果查詢要素，以及接口提供方希望接入方怎么識別交易成功與否，接入方怎么清晰地定位交易結果？關于交易結果，從明確到不確定，可以分為：明確成功，明確失敗，交易處理中（含交易結果未知狀態），那么采用任何一種應答方案，基本原則是要能讓接入方識別這三種狀態。如果識別機制簡單易懂，可見即可得，那么不失為一種良好的設計方案。本文從這個基本點出發，漸進演變，闡述了三種應答碼方案。另外，這三種方案，有一個共同的前提，就是應答報文都會返回具體應答碼respCode和應答消息respMsg，respCode定義為兩位字符，respMsg為具體中文描述。

2. 應答碼方案

2.1方案一：只返回具體應答碼

優點：系統設計簡單，系統提供方只需要按照自己的規則返回應答。

缺點：接入復雜，需要清楚各種應答碼的具體意義。

方案一：非查詢交易返回respCode，查詢交易返回respCode+origResp Code，如下表所示：

接入方需要區分交易的異步應答、交易的同步應答、交易查詢應答，按照前臺交易、后臺交易、查詢交易、同步和異步，可以分為以下場景：

從上面的場景可以看出，這種設計有二義性的問題。具體地，第一，同一個應答碼00在異步版的同步應答和異步通知代表的是不同的意義，00接入方在處理同步應答時需要當做受理成功處理，需要繼續查詢或著等異步通知;但是00在異步通知的場景表示處理成功。二義性的設計就會給接入帶來一些溝通成本，增加處理邏輯。第二，在查詢的時候，同一個應答碼，接入方也是要區分對待的，區分前臺交易還是后臺交易;由于本文討論的支付系統包括前臺交易和后臺交易兩種模式，前臺只有成功一個終態，其他都是處理中，當前查詢失敗也不算訂單失敗，因為持卡人還可以跳轉到支付系統的頁面換卡重新支付，直到支付成功，當然這個問題可以通過設置支付超時時間來解決，就是在請求報文中設置一個超時時間，到達這個時間支付系統設置為終態，持卡人再發起支付會返回超過時間限制，避免接入方一直等待支付結果。第三，查詢的時候是有兩層應答碼的，一個是原交易的應答碼，一個表示查詢本身的應答碼，而查詢交易更關注原交易的應答碼，兩層結構增加了解析的復雜性。第四，簽名驗簽這些錯誤，對于查詢交易，是查詢本身失敗，不代表原交易的狀態。

另外一方面，這種應答碼設計將應答的狀態與應答碼合并表達，系統一旦發布，處理中的應答碼不可以增加，否則接口口徑需要同步變更，商戶的接入也有依賴，可能需要同步修改。

2.2方案二：增加應答碼歸類

優點：結構清晰，業務邏輯透明

缺點：系統設計冗余，接入復雜，并沒有解決根本問題

方案二：非查詢交易應答碼返回result+respCode，查詢交易返回result+ respCode+origResult+OrigRespCode，如下表所示：

在方案一的基礎上，提出一種改進方案，將應答碼回歸到反應具體錯誤信息，增加一個應答要素——交易結果狀態status（SUCCESS：成功，FAILURE：失敗，UNKNOWN：未知，PROCESSING：處理中），也就是將應答碼分類，接入方不再關注每個應答碼是什么狀態，只需要關心result。那么，方案一中的問題1可以通過返回status=處理中識別同步受理成功，返回status=成功來定位處理成功，其他問題是否能夠迎刃而解呢？再三推演，本系統有查詢交易，查詢交易返回status=SUCCESS到底表示查詢成功還是原交易成功，這就引入了新的問題。按照將應答碼respCode弱化接入感知性，增加交易結果status變量的設計思路，必須再增加一個origStatus，顯然接口設計復雜而無明顯改進。另外，陷入了查詢交易和原交易兩層的絕對區分，而查詢交易本身的狀態接入方是不關心的，接入方更關心原交易的狀態。

2.3方案三：在應答碼歸類的基礎上增加交易狀態

優點：解析簡單，業務邏輯清晰

方案三：非查詢交易返回returnCode+respCode，查詢交易返回status+ returnCode+respCode，異步通知返回status+respCode，如下表所示：

天下武功唯快不破，所有的方案，如果能夠可見即可得，快速接入那么不失為好設計。前面兩個方案，無法解決接入方識別是查詢本身的狀態還是被查詢的原交易的狀態的判斷，沿著方案二的思路又有過度設計的弊端。追根溯源，接口應答碼需要解決的問題是什么？第一，容易識別交易狀態，但是又不需要關心應答碼respCode的變化;第二，能夠區分查詢錯誤還是原交易錯誤，第三，接入簡單。

沿著這個思路，我們把應答碼設計分兩層，第一層是返回大的歸類，解決應答碼分類的問題，第二層解決返回具體應答碼，業務邏輯透明，接入方不需要識別所有應答碼來做業務邏輯判斷。第一層就是增加一個變量——返回碼，表示此次交易請求的業務結果，查詢交易表示查詢操作的業務結果，具體交易結果，以交易狀態碼為準，可以清晰區分同步受理結果和異步處理結果，解決了方案一中的問題1。另外，編碼采用工整的6位字符，而不是具有語義的英文單詞，沒有二義性，也解決了方案二中到底是查詢成功還是原交易成功的問題，表示本次交易的狀態，如果是查詢交易，RT1000就表示查詢成功了，具體被查詢交易的狀態以對應的狀態碼來識別，這里也需要引入第二個業務強相關的變量——交易狀態，status（SUCCESS：交易成功，PROCESSING：交易處理中，UNKNOWN：交易結果未知，FAILURE：交易失敗，REFUNDED：已退貨），僅查詢交易返回這個status。

返回碼按照常見應答歸類定義為以下值：

按照方案三，我們可以提供一致的方案展示方案一種各個場景應答碼解釋。

非查詢交易，不論同步版還是異步版：

查詢交易，接入方不需要區分前臺交易和后臺交易的差別處理，因為應答的時候前臺交易不會出現原交易失敗的狀態，所以對接入方透明，不感知。

對于異步通知，同樣，不區分前臺交易和后臺交易，前臺交易不會出現失敗的狀態，因為支付系統設計在前言中已經陳述過，前臺交易只有明確成功才發通知。而且后臺交易的異步通知，原交易明確成功過或者明確失敗都會發，作為應答結果的一種接口，其作用跟查詢交易成功的結果一致的，所以不會出現冗余的returnCode=RT1000，只需要識別交易狀態status。

3. 結語

方案三的設計層級分明，解除了接入方對具體應答碼的依賴關系，同時，引入了兩層應答碼，返回碼returnCode做一層交易狀態歸類，讓應答碼respCode在查詢和非查詢交易中，都一致地代表具體應答信息，不需要增加origRespCode這樣的變量。另外查詢交易增加應答status來識別原交易的狀態，做到一致性的同時具有完備性，完整地表達應答一支交易的處理狀態。

作者簡介

劉丹（出生年月：1984.10.20），性別：女，民族：漢族，籍貫（省市）：湖北孝感，職稱：開發工程師，學歷：碩士研究生，單位：中國銀聯股份有限公司，研究方向：計算機軟件。