接口设计之应答码方案升级研究

摘要：对于支付系统，需要以接口形式提供给商户接入。系统设计中涉及接口调用，就有应答码，应答码方案不同，给接入方的开发工作有很大的影响性，层级分明的应答码方案可以给接入方和接口提供方带来事半功倍的效果。本文从常见的应答码方案论证演变，推出一种新的应答码方案。

关键词：接口设计;应答码;交易结果

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），性别：女，民族：汉族，籍贯（省市）：湖北孝感，职称：开发工程师，学历：硕士研究生，单位：中国银联股份有限公司，研究方向：计算机软件。