說起支付，每個人可能想到的是微信、支付寶，其實他們都是后來者，屬于第三方支付，論歷史還得屬銀行久遠(yuǎn)。在中國銀行不僅代表了最正確和最前沿的支付的方向，更代表了社會主義的最先進(jìn)的生產(chǎn)力。尤其是在“互聯(lián)網(wǎng)+”潮流下，各個銀行每年在互聯(lián)網(wǎng)信息化方面投入上百億，爭當(dāng)時代的引領(lǐng)者。鄙人有幸對接了中國農(nóng)行的支付方式，
下面分享一些學(xué)到的設(shè)計理念，文檔入口：https://bank.u51.com/ebus-two/docs
-
暴露狀態(tài)碼。
當(dāng)
RetunCode為EUNKWN或PR0000或EOSCUNKWN或AP5168時，不代表交易失敗，僅代表交易結(jié)果不明確，交易結(jié)果需要進(jìn)行查證確認(rèn)。只需要告訴用戶不明確結(jié)果和成功，明確的失敗不需要告訴用戶，讓他們自己猜或者主動測試。
不用解釋每個錯誤碼具體含義，以免增加對接方心智負(fù)擔(dān)。
不需要提供一個錯誤碼和對應(yīng)業(yè)務(wù)場景的語義列表，以免帶來更多的維護(hù)成本。
-
提供Java版本的Demo
https://bank.u51.com/ebus-two/docs/#/quick-start/brefore-start
給對接方提供一個java版本的demo有助于業(yè)務(wù)方快速了解業(yè)務(wù)，同時給demo文件一定要包含兩種以上的不同的字符集編碼格式，
不要用UTF8，要給打開demo的人一些想象空間和驚喜，讓他們自己去猜到底應(yīng)該用哪種字符集解析。
不同字符集體現(xiàn)了內(nèi)部多樣化的開發(fā)環(huán)境，也是向?qū)臃秸故咀约很泴嵙Φ囊粋€窗口。
雖然有些中文是亂碼，但是很多都是代碼注釋信息，俗話說
代碼即注釋，這也是代碼質(zhì)量的一種自信。-
不要提供其他的語言的包
java才是主流，用其他語言比如php、go的公司肯定做不大，要直接在編程語言上幫公司過濾沒有價值的客戶，這也是
技術(shù)要理解和支持業(yè)務(wù)發(fā)展的表現(xiàn)。不懂java、不會運行java-demo的對接方不是目標(biāo)用戶群。
-
不要提供清晰的加簽、驗簽流程說明
不要用自然語言清晰的描述加簽驗簽流程或者提供非java語言的代碼案例，要讓對接方看demo或者自己猜，這也是判斷是否是目標(biāo)用戶群的一個方式。
一定不要用UTF8編碼,比如可以用GBK或者其他編碼，同時把編碼和加簽驗簽結(jié)合起來，一來可以凸顯自己的特色，同時也能幫對接方回憶一下字符集相關(guān)的知識。
采用多樣的數(shù)據(jù)格式，比如提供http請求接口要采用json數(shù)據(jù)格式，給用戶的回調(diào)采用xml格式，xml格式擁有悠久的歷史，這也是校驗對接方技術(shù)人員工作經(jīng)驗和技術(shù)水平的一種方式。
-
只提供錯誤的案例
{ "MSG": { "Message": { "Version": "V3.0.0", "Format": "JSON", "Common": { "Channel": "" }, "Merchant": { "ECMerchantType": "EBUS", "MerchantID": "103882200000958" }, "ReturnCode": "AP7745", "ErrorMessage": "該終端號未在當(dāng)前商戶維護(hù)，請聯(lián)系銀行工作人員前往網(wǎng)絡(luò)金融運營管理平臺進(jìn)行維護(hù)", "TrxType": "ScanPayOrderReq", "OrderNo": "No20220909100002751953", "OrderAmount": "1.00", "ScanPayQRURL": "" }, "Signature-Algorithm": "SHA1withRSA", "Signature": "dSlArjRftdC3uXVtA4mwDppnSbgDa1gOQMnZ4ZYluk5hlXGtW0b2OqCjuqrX2Oxwt5obszuWXk2qkzWcSiyvp64hP7cC7Ps+5FKM3SQwVbnvXLTVM2ODYtH6lG1s3ogSTzEWyvb+Tukqm8SupnlI8ycsfayRvd80qGUAMn9Msj0=" } }
給用戶提供接口只提供錯誤的案例，幫助用戶加深錯誤的印象。比如上面案例中ScanPayQRURL在成功場景下返回的格式是什么，要讓對接方自己測試。
-
接口升級要具備一定不兼容性。
比如舊接口和新接口的返回值：
https://pay.abchina.com/ebusperbank/PaymentModeNewAct.ebf?TOKEN=15753560246988869886
token和TOKEN，對接方需要取到對應(yīng)的值進(jìn)行處理。在設(shè)計的時候一定要采用不同的字段，顯示的向?qū)臃絺鬟_(dá)內(nèi)部接口升級的事實，要讓他們感知到自己的存在。
不要讓對接方以為僅僅換一個接口名，參數(shù)返回值完全都完全相同，要讓他們對自己的改動做check，養(yǎng)成良好的習(xí)慣。 返回結(jié)構(gòu)多樣化
比如：下面的請求結(jié)果，一個采用平鋪、一個采用嵌套，甚至可以更加不拘一格寫出更加多樣的結(jié)構(gòu).
這樣可以向?qū)臃秸故咀约喊蓍_放多樣化的代碼風(fēng)格。
給對接方留下疑問：是文檔寫錯了？還是真是這樣設(shè)計的？這樣是不是就不能復(fù)用了？
-
參數(shù)和字段命名
- 要讓文檔發(fā)揮不可替代的作用，否則文檔編寫意義就沒有那么大了，比如
NewOrderNo: 退款單號，用于查詢退款狀態(tài)。
OrderNo：支付單號。
這樣沒有對應(yīng)的文檔說明，很難知道對應(yīng)字段的含義。
- 要傳一些沒有看起來沒有必要的參數(shù)
退款接口讓業(yè)務(wù)方必傳日期和時間
OrderDate String是10 退款日期 2019/12/23 OrderTime String是8 退款時間 11:55:30這樣可以用自己服務(wù)器的時間和對接方請求的時間做一個對比，以便計算網(wǎng)絡(luò)延遲。
-
內(nèi)部的常識就是業(yè)界的常識
下面的事情是沒有必要告知對接方的
采用了post請求，但是選用了
urlencoded form格式。字符集是非UTF8編碼。
數(shù)據(jù)真正格式是XML，驗簽的簡短的案例是JSON，其實不完全適用，甚至?xí)幸恍┱`導(dǎo)。
比如：交易相關(guān)的請求的url是https://pay.abchina.com/ebus/ReceiveMerchantTrxReqServlet，你也不需要寫在對應(yīng)的接口文檔上，你只需要寫
com.abc.pay.client.ebus.common.EBusMerchantCommonRequest,懂的自然懂，不懂的說明你沒有看java版的demo。 -
節(jié)約成本
降本增效是未來發(fā)展的主旋律，在一些服務(wù)器資源相關(guān)方面也是應(yīng)該有所考量。
-
用戶超時未支付以后
不要主動關(guān)閉支付單，要始終保持支付單的狀態(tài)是未支付。超時關(guān)單一般用異步消息，訂單量大的時候發(fā)消息也是一種浪費，所以超時未支付不更改狀態(tài)。
對接方在支付超時后查詢支付單狀態(tài)依然要保持未支付的狀態(tài)，千萬不要結(jié)合“status = 未支付 && exipre_time < 當(dāng)前時間” 給對接方轉(zhuǎn)換成一個closed狀態(tài)，要最原始的狀態(tài)暴漏給對接方。
-
回調(diào)通知盡可能的少
只回調(diào)業(yè)務(wù)方一次，不論對方是否成功處理，不做重試。
最多回調(diào)3次。
- 實踐是檢驗真理的唯一標(biāo)準(zhǔn)
不需要整理對接方常見的問題，并回答。
不需要畫流程圖，不需要對異常情況進(jìn)行總結(jié)。
如果對接方對流程有疑問讓業(yè)務(wù)方自己做實驗嘗試，這個可以保證最新最準(zhǔn)確的結(jié)果。
銀行系統(tǒng)設(shè)計博大精深，個人能力有限只能略微學(xué)到一些皮毛，不過在網(wǎng)上看到過一些其他人也有不同的收獲：
