外围对接模块开放协议
一、适用对象
具备开发能力的第三方开发人员。
二、协议约定
地址：对接模块所在计算机的IP地址，若在服务器本机即为127.0.0.1，该地址在服务器的设备列表中配置。
端口号：外围对接模块的侦听端口，建议使用端口范围{60000-60999}，为避免与操作系统常用端口冲突，请勿使用小于1024的端口。
通信方式：socket短连接
报文编码：所有报文字段使用JSON格式封装，GBK编码。
三、定单接收接口
功能描述：该接口用于服务器向外围对接模块发送定单交易请求。
| 序号 |
字段名 |
类型 |
长度 |
描述 |
| 1 |
action |
字符串 |
2 |
交易指令 CZ:充值 |
| 2 |
chargeId |
整形 |
- |
定单流水号（必须保持原值返回） |
| 3 |
chargeAcct |
字符串 |
50 |
被充值账号 例如手机号码 |
| 4 |
chargeCash |
金额 |
- |
充值金额 以元为单位，精确小数点后三位 例如 100.000 |
| 5 |
chargeType |
整形 |
- |
业务类型
0:话费 1:Q币 2:QQ会员 3:游戏
4:水电气 5:流量 6:票务 7:固话 8:宽带 9:油卡 |
| 6 |
amount |
整形 |
- |
充值数量 默认为1，充值游戏时需要使用 |
| 7 |
faceValue |
金额 |
- |
单品面值 充值游戏时需要使用 |
| 8 |
var1 |
字符串 |
20 |
备用参数1 |
| 9 |
var2 |
字符串 |
20 |
备用参数2 |
| 10 |
var3 |
字符串 |
20 |
备用参数3 |
| 11 |
var4 |
字符串 |
20 |
备用参数4 |
| 12 |
productSn |
整形 |
- |
产品编码，特殊游戏商品需要用到该字段值 |
| 13 |
nbrArea |
字符串 |
20 |
被充值账号的归属地 |
| 14 |
cardSn |
字符串 |
30 |
充值卡卡号 |
| 15 |
cardPassword |
字符串 |
30 |
充值卡密码 |
| 16 |
agentAcct |
字符串 |
50 |
代理工号，多账号环境下需要用到 |
| 17 |
agentPass |
字符串 |
50 |
代理工号密码 |
| 18 |
cardId |
整形 |
- |
充值卡ID，必须原值返回 |
| 19 |
retRsn |
字符串 |
50 |
定单标识码，必须原值返回 |
| 20 |
sign |
字符串 |
32 |
签名 按以下方法拼接参数的值及密钥取MD5值
md5(chargeId + chargeAcct + var1 + var2 + var3 + var4 + chargeCash + md5key)
|
例如下面的数据包，使用的md5key=bff0378ea5ef0d5d
{"action":"CZ","chargeId":196,"chargeAcct":"13530017201","chargeCash":100.000,"chargeType":0,"amount":1,"faceValue":100.000,"var1":"","var2":"","var3":"","var4":"","productSn":0,"nbrArea":"广东省深圳-移动","cardSn":"","cardPassword":"","agentAcct":"","agentPass":"","cardId":0,"retRsn":"0","sign":"8e6f40693e0380fdb0c504768e5e70ab"}
接收定单后，应立即同步返回一个应答，格式样例如下：
{"action":"CZ","chargeId":196,"retCode":0,"retDetail":"定单已接收","retRsn":"","sign":"6de2b30585c463d5fa6d7188400522ed"}
四、定单结果回调推送接口
功能描述：该接口用于外围对接模块向服务器推送定单交易结果，定单交易结束后，对接模块主动向服务器发送结果回调通知，回调接收端口: 50899 ，回调接收的IP地址在接收定单接口中确定，即接收定单时数据包的发送方IP地址。
| 序号 |
字段名 |
类型 |
长度 |
描述 |
| 1 |
action |
字符串 |
2 |
交易指令 原值返回 |
| 2 |
chargeId |
整形 |
- |
定单流水号 原值返回 |
| 3 |
retCode |
整形 |
- |
交易结果 0:未处理 1:充值成功 2:充值结果不确定 3:充值失败 |
| 4 |
retDetail |
字符串 |
100 |
交易结果的详细说明 |
| 5 |
retRsn |
字符串 |
50 |
定单标识码，必须原值返回 |
| 6 |
userContent |
字符串 |
100 |
可透传显示给下级用户的描述说明，如号码欠费、空号等提示信息。 |
| 7 |
retCost |
金额 |
10 |
定单实际成本 以元为单位精确小数点后三位 例如: 99.100 |
| 8 |
retBalance |
金额 |
15 |
代理账户余额，该余额用于管理端显示该端口模块的可用余额。 |
| 9 |
retCash |
金额 |
10 |
实际成功金额，该字段用于返回部分成功的金额 |
| 10 |
sign |
字符串 |
32 |
签名 按以下方法拼接参数的值及密钥取MD5值
md5(chargeId + retCode + retRsn + md5key) |
异步回调通知样例数据包：
{"action":"CZ","chargeId":196,"retCode":1,"retDetail":"充值成功","retRsn":"","userContent":"","retCost":99.100,"retBalance":58921.980,"retCash":100.000,"sign":"30b0e1dc67695ebfd501ac1ab9fcb7fd"}
服务器接收到回调数据包后，会同步应答 OK ，外围程序接收到OK后就不要再发送回调数据包了。
