接口設(shè)計之應(yīng)答碼方案升級研究

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

關(guān)鍵詞：接口設(shè)計;應(yīng)答碼;交易結(jié)果

1.前言

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

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

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

2. 應(yīng)答碼方案

2.1方案一：只返回具體應(yīng)答碼

優(yōu)點：系統(tǒng)設(shè)計簡單，系統(tǒng)提供方只需要按照自己的規(guī)則返回應(yīng)答。

缺點：接入復(fù)雜，需要清楚各種應(yīng)答碼的具體意義。

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

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

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

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

2.2方案二：增加應(yīng)答碼歸類

優(yōu)點：結(jié)構(gòu)清晰，業(yè)務(wù)邏輯透明

缺點：系統(tǒng)設(shè)計冗余，接入復(fù)雜，并沒有解決根本問題

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

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

2.3方案三：在應(yīng)答碼歸類的基礎(chǔ)上增加交易狀態(tài)

優(yōu)點：解析簡單，業(yè)務(wù)邏輯清晰

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

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

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

返回碼按照常見應(yīng)答歸類定義為以下值：

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

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

查詢交易，接入方不需要區(qū)分前臺交易和后臺交易的差別處理，因為應(yīng)答的時候前臺交易不會出現(xiàn)原交易失敗的狀態(tài)，所以對接入方透明，不感知。

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

3. 結(jié)語

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

作者簡介

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