根据我们之前的整体介绍，和业务方交互我们使用的是 HTTP 协议。我们称提供 WEB 接口支持的服务为开放平台（其实每家公司都有自己的叫法，领会精神）。开放平台的职责为支付平台化后，系统内部接口不可对外，所有的外部系统交互统一与开放平台交互，完成服务收口。所以一些格式、参数校验可以在这里完成，进而将请求转发的服务层。
由于这些接口都是提供给外部调用方的，接口的设计好坏直接影响到了对接方的使用体验。某种程度上，它还是我们的脸面。作为一名专业的开发者，我们都不希望自己设计的接口被别人吐槽不好用、不专业、能用。因此，本篇幅着重分析如何设计 API，希望大家能够重视起来，做一个专业的开发者。
接口需求
首先，我们和业务方通过 HTTP 协议进行通信，接口以 URL 的形式提供，使用目前最主流的 JSON 格式，并且以 application/json 的格式进行 POST 提交。接口分两种：服务接口、通知回调接口。服务接口由开放平台提供，供业务方调用。回调通知接口由业务平台提供，由支付系统进行主动调用。所以，需要设计的是服务接口。
微信支付接口设计
这里是 微信支付接口 的入口地址，不同的支付场景读者可以自行点进去查看。
我们还是以扫码支付的流程进行分析。点击 Native 支付，我们可以看到如下的图：
基本上对接微信支付，从开发交易到后期的对账，这些 API 都在这里了。这里我简单列了个表格，方便大家参考。
| 接口 | URI |
|---|---|
| 统一下单 | https://api.mch.weixin.qq.com/pay/unifiedorder |
| 查询订单 | https://api.mch.weixin.qq.com/pay/orderquery |
| 关闭订单 | https://api.mch.weixin.qq.com/pay/closeorder |
| 申请退款 | https://api.mch.weixin.qq.com/secapi/pay/refund |
| 查询退款 | https://api.mch.weixin.qq.com/pay/refundquery |
| 下载交易账单 | https://api.mch.weixin.qq.com/pay/downloadbill |
| 下载资金账单 | https://api.mch.weixin.qq.com/pay/downloadfundflow |
OK，我们看到微信支付的接口设计是 RESTful 风格。这里也提一下 RESTful 设计时常用的准则：
- 见名知意，可读性强。如 https://gitbook.cn/gitchat/categories/5d8b7c3786194a1921979122 一看就是分类。
- 不要搞一些花里胡哨的外语，以为自己很酷。比如 https://api.famous/donald-trump 不知道的人以为是介绍特朗普，其实可能只是某个开发同学的 demo 首页。
- 不要在结尾加/，不要使用_，不要使用大写。
- 不要英文中文拼音混用。
- 一般不需要 RESTful 提示信息和版本，如 https://gitbook.cn/gitchat/v2/restful/categories/1013 太臃肿。
举例，如微信查询退款的接口也可以设计为 /pay/refund-query，但是千万不要搞一个 /pay/refundQuery 为难调用者。
支付宝支付接口设计
这里是 支付宝开放平台文档 的入口地址，这个页面偏从零开始，如何使用 SDK 进行对接，点击后可以看到如下页面：
支付宝我们同样以扫码支付的流程进行分析。
第一幅图是扫码支付快速接入中对【搭建和配置开发环境】中的说明，可以看到调用支付宝接口可以使用其提供更多 SDK，很重要的一点是配置参数 URL 时统一的值https://openapi.alipay.com/gateway.do。第二幅图是【API】列表中扫码支付的说明。
再来看看 支付 API 文档 的介绍，注意图中标红的部分：
通过以上分析，可以看出支付宝接口使用统一的网关，只有一个入口，内部使用参数进行路由。这种 API 的设计方式我们称之为命令模式。是一种大一统的设计方案，缺点是做负载均衡会稍微麻烦点，优点是扩展方便，直接增加 method 的值即可进行内部路由。
支付规范命名参考
统一的命名规范带来的好处不言而喻。为此，我整理了一下微信和支付宝中高频词汇的英文命名，大家觉得好的可以参考，当然自己用起来舒服最重要。
| 名称 | 微信 | 支付宝 |
|---|---|---|
| 商户号 | mch_id | |
| 应用 ID | app_id | app_id |
| 随机字符串 | nonce_str | |
| 签名 | sign | sign |
| 签名类型 | sign_type | sign_type |
| 标题 | subject | |
| 商品描述 | body | body |
| 商户订单号 | out_trade_no | out_trade_no |
| 支付订单号 | transaction_id | trade_no |
| 交易起始时间 | time_start | |
| 交易结束时间 | time_expire | |
| 标价金额 | total_fee | total_amount |
| 通知地址 | notify_url | notify_url |
| 交易类型 | trade_type | |
| 交易状态 | trade_state | trade_status |
| 商品 ID | product_id | goods_id |
| 返回状态码 | return_code | code |
| 返回信息 | return_msg | msg |
| 业务结果 | result_code | sub_code |
| 业务结果描述 | sub_msg | |
| 错误代码 | err_code | |
| 错误代码描述 | err_code_des |
