|
|
@@ -0,0 +1,127 @@
|
|
|
+[TOC]
|
|
|
+
|
|
|
+# 接口规则
|
|
|
+
|
|
|
+## 协议规则
|
|
|
+
|
|
|
+调用API必须遵循以下规则：
|
|
|
+
|
|
|
+| 规则 | 说明 |
|
|
|
+| ---- | ---------------------------------------------------- |
|
|
|
+| 传输方式 | HTTP/HTTPS |
|
|
|
+| 提交方式 | 采用POST方法提交 |
|
|
|
+| 数据格式 | 提交和返回数据都为JSON格式: "Content-Type", "application/json" |
|
|
|
+| 字符编码 | 统一采用UTF-8字符编码 |
|
|
|
+| 安全机制 | 签名或者IP白名单 |
|
|
|
+| 签名算法 | 如安全机制未签名，RSA(2048)/和支付宝RAS2方式签名一样 |
|
|
|
+| 签名要求 | 如安全机制未签名，请求和接收数据均需要校验签名 |
|
|
|
+
|
|
|
+## 签名/验签规则
|
|
|
+
|
|
|
+平台将请求参数字段**排序后**序列化为键值对，并使用&链接成字符串
|
|
|
+
|
|
|
+对字符串进行rsa2048签名
|
|
|
+
|
|
|
+```java
|
|
|
+String toSignContent = "appid=" + x.getAppId() +
|
|
|
+ "&billKey=" + x.getBillKey() +
|
|
|
+ "&nonceStr=" + x.getNonceStr() +
|
|
|
+ "&timeStamp=" + x.getTimeStamp();
|
|
|
+```
|
|
|
+
|
|
|
+商户请自行使用平台提供的公钥以同样操作方式进行验签
|
|
|
+
|
|
|
+**注意: sign字段本身不参与验签**
|
|
|
+
|
|
|
+## 安全规范
|
|
|
+
|
|
|
+### 签名工具
|
|
|
+
|
|
|
+RAS密钥可以使用支付宝提供的工具计算 [密钥生成工具](http://p.tb.cn/rmsportal_6680_secret_key_tools_RSA_win.zip)  开发资源有限，目前只支持rsa，格式为pkcs8，长度为2048
|
|
|
+
|
|
|
+# 接口说明
|
|
|
+
|
|
|
+平台发起调用，商户收到调用信息并验证签名后返回对应的业务信息
|
|
|
+
|
|
|
+# 查询缴费单
|
|
|
+
|
|
|
+## 应用场景
|
|
|
+
|
|
|
+通过该接口获取终端用户的预存与欠费情况
|
|
|
+
|
|
|
+## 请求参数
|
|
|
+
|
|
|
+| 参数 | 类型 | 必填 | 描述 |
|
|
|
+| --------- | ------ | -- | ------------ |
|
|
|
+| appId | String | 是 | 商户号,由平台提供,唯一 |
|
|
|
+| billKey | String | 是 | 终端用户机表号 |
|
|
|
+| nonceStr | String | 是 | 随机字符串 |
|
|
|
+| timeStamp | String | 是 | 请求发起的时间戳 |
|
|
|
+| sign | String | 是 | 签名 |
|
|
|
+
|
|
|
+## 返回结果
|
|
|
+
|
|
|
+| 变量名 | 类型 | 描述 | 示例值 |
|
|
|
+| :----------- | :----- | :------------------ | :------------ |
|
|
|
+| appId | String | 商户号,由平台提供,唯一,原样回传即可 | 1234567 |
|
|
|
+| respCode | String | 调用结果,详见错误码 | 00000 |
|
|
|
+| respMsg | String | 错误描述 | success |
|
|
|
+| timeStamp | String | 请求返回的时间戳 | 1745393406 |
|
|
|
+| billKey | String | 终端用户机表号 | HC202110257 |
|
|
|
+| customerName | String | 终端用户名称 | XXX小区X栋XX户李XX |
|
|
|
+| balance | long | 用户预存金额(单位:分) | 0 |
|
|
|
+| payAmount | long | 用户本期欠费金额(单位:分) | 100 |
|
|
|
+
|
|
|
+## 错误码
|
|
|
+
|
|
|
+| 错误码 | 描述 |
|
|
|
+| :------ | :------------------- |
|
|
|
+| 00000 | 成功 |
|
|
|
+| DEF0002 | 用户未欠费 |
|
|
|
+| DEF0005 | 超过缴费时间 |
|
|
|
+| DEF0010 | 用户不存在 |
|
|
|
+| DEF0012 | 该用户不支持网上缴费，请联系公共事业单位 |
|
|
|
+| DEF0006 | 其他异常 |
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+# 缴费单销账
|
|
|
+
|
|
|
+## 应用场景
|
|
|
+
|
|
|
+用户在平台完成缴费，需要调用商户的系统进行销账。
|
|
|
+
|
|
|
+## 请求参数
|
|
|
+
|
|
|
+| 参数 | 类型 | 必填 | 描述 |
|
|
|
+| :--------- | :----- | :- | :-------------- |
|
|
|
+| appId | String | 是 | 商户号,由平台提供,唯一 |
|
|
|
+| billKey | String | 是 | 终端用户机表号 |
|
|
|
+| payDate | String | 是 | 缴费交易日期 yyyyMMdd |
|
|
|
+| bankBillNo | String | 是 | 缴费交易流水号 |
|
|
|
+| payAmount | String | 是 | 缴费金额,单位:分 |
|
|
|
+| nonceStr | String | 是 | 随机字符串 |
|
|
|
+| timeStamp | String | 是 | 请求发起的时间戳 |
|
|
|
+| sign | String | 是 | 签名 |
|
|
|
+
|
|
|
+## 返回结果
|
|
|
+
|
|
|
+| 变量名 | 类型 | 描述 | 示例值 |
|
|
|
+| :-------- | :----- | :------------------ | :--------- |
|
|
|
+| appId | String | 商户号,由平台提供,唯一,原样回传即可 | 1234567 |
|
|
|
+| respCode | String | 调用结果,详见错误码 | 00000 |
|
|
|
+| respMsg | String | 错误描述 | success |
|
|
|
+| timeStamp | String | 请求返回的时间戳 | 1745393406 |
|
|
|
+
|
|
|
+## 错误码
|
|
|
+
|
|
|
+| 错误码 | 描述 |
|
|
|
+| :------ | :------------------- |
|
|
|
+| 00000 | 成功 |
|
|
|
+| DEF0002 | 用户未欠费 |
|
|
|
+| DEF0005 | 超过缴费时间 |
|
|
|
+| DEF0010 | 用户不存在 |
|
|
|
+| DEF0012 | 该用户不支持网上缴费，请联系公共事业单位 |
|
|
|
+| DEF0013 | 金额不符合规则 |
|
|
|
+| DEF0006 | 其他异常 |
|
|
|
+
|
