一、概述
本接口文档用于商户定单的接入，承载手机充值、固定电话充值、宽带充值、手机流量充值等业务接入。
1）使用过程中，由接入服务提供商向开发人员提供技术支持。
2）接入服务提供商可通过本文末联系方式向我公司获得原始技术支持。
3）协议用途以及适合对象
a、该通讯协议规范了接入的业务代码，通讯方式等。
b、适合于代理商营业系统的技术开发人员参照使用。
c、代理商自有营业系统需要将自有营业系统的定单交由本系统自动处理时可参照本协议中所规范的内容开发接入程序。
二、通讯协议
1、通讯方式 HTTP 服务器同步返回交易结果。
1) 双方采用HTTP方式通讯； Method 采用 POST 向服务器发送数据。
2、服务器地址 向商务联系索取
HTTP方式: http://服务器地址:50080/API
档中样例帐号：api_test 密钥：0FE8E43F53BB5848 此账号为示例，正式账户信息请向商务申请。
3、签名算法: Md5
4、充值接口不允许有重复定单提交，相同的orderId即视为同一笔定单，重复提交定单将返回该定单已有的状态。
5、充值接口不提供返销冲正功能，所有提交成功的交易不可撤销。
6、中文编码：中文均采用GBK编码。
7、网络故障重试，在网络有故障情况下，接入方没有收到服务器返回的结果，可以作以下处理：
1） 接入方可多次重新发送这个定单，但定单号码必须与原定单完全一致。即orderId必须相同。
2） 不建议频繁重发，补发定单前应调用查询接口查询该定单状态再决定是否再次重发。
3） 补发时间应该间隔10秒以上。
4） 没有查询到准确的定单状态为缴费失败或者取消处理时，请不要给终端退款，以免造成资损。
8、绑定来路IP 代理商提供来路IP给服务器绑定，只允许绑定的IP做交易；未绑定IP时，允许所有IP交易。
9、重置密钥 如需重置密钥，请联系商务负责人发送到您的安全邮箱；安全邮箱由您开户时提供绑定。
三、数据报文结构
数据报文分为公共部分和业务部分；业务部分的字段用于描述业务接口，不同的业务接口字段不同；公共部分为全部业务接口的必须部分。
| 序号 |
字段名 |
字段含义 |
字段长度 |
说明 |
| 1 |
sign |
签名 |
32字节 |
小写md5值 |
| 2 |
agentAccount |
商户账号 |
1-20字节 |
由服务方提供 |
| 3 |
busiBody |
业务接口实体 |
- |
参照第五节业务接口 |
四、签名
为保障通信数据的安全，要求每个报文必须签名，请接入方根据以下流程签名后以sign字段提交。
1）sign = md5(busiBody+Md5Key)
2）sign为32位小写 md5值。
五、交易接口
1、 账户余额查询接口
该交易由接入方发起，提交的数据报中包含以下字段:
| 序号 |
字段名 |
字段含义 |
字段长度 |
说明 |
| 1 |
action |
交易指令码 |
2字节 |
固定值: YE |
余额查询返回字段：
| 序号 |
字段名 |
字段含义 |
字段长度 |
说明 |
| 1 |
agentAccount |
商户账号 |
1-20字节 |
原值返回 |
| 2 |
action |
交易指令码 |
2字节 |
固定值: YE |
| 3 |
agentBalance |
预存账户余额 |
1-20字节 |
账户余额 |
| 4 |
agentProfit |
预存账户佣金 |
1-20字节 |
账户佣金 |
| 5 |
agentName |
商户名称 |
50字节 |
商户完整名称 |
| 6 |
errorCode |
错误代码 |
4字节 |
参照错误代码表 |
| 7 |
errorDesc |
错误消息 |
50字节 |
文字说明错误 |
样例数据
业务报文:{"action":"YE"}
签名报文:{"action":"YE"}0FE8E43F53BB5848
提交：
{
"sign": "676c1e0edfb21873cc74d223bf50dead",
"agentAccount": "api_test",
"busiBody": {
"action": "YE"
}
}
返回：
{
"action": "YE",
"agentAccount": "api_test",
"agentBalance": 100,
"agentProfit": 0,
"agentName": "测试账号",
"errorCode": 1,
"errorDesc": "操作完成"
}
2、 代理商定单查询接口
该交易由接入方发起，提交的数据报中包含以下字段：
| 序号 |
字段名 |
字段含义 |
字段长度 |
说明 |
| 1 |
action |
交易指令码 |
2字节 |
固定值: CX |
| 2 |
orderId |
定单号 |
1-20字节 |
充值定单号。 |
代理商定单查询返回字段：
| 序号 |
字段名 |
字段含义 |
字段长度 |
说明 |
| 1 |
action |
交易指令码 |
2字节 |
固定值: CX |
| 2 |
agentAccount |
商户账号 |
1-20字节 |
原值返回 |
| 3 |
agentBalance |
商户余额 |
1-20字节 |
当前余额 |
| 4 |
orderId |
定单号 |
1-20字节 |
接入方定单号 原值返回 |
| 5 |
chargeId |
交易流水号 |
1-20字节 |
服务端交易流水号 |
| 6 |
orderStatuInt |
定单状态代码 |
1-2字节 |
定单状态与定单状态代码意义相同，
定单状态用于人工阅读，
定单状态代码便于程序识别。
0：等待处理 1：暂停处理
2：正在处理 6：正在缴费
11：处理成功 16：缴费成功
20：取消处理 21：处理失败
26：缴费失败 99：冻结 |
| 7 |
orderStatuText |
定单状态 |
1-20字节 |
文字说明 |
| 8 |
orderPayment |
定单支付金额 |
1-20字节 |
交易成功定单的实际扣款金额 |
| 8 |
errorCode |
错误代码 |
4字节 |
参照错误代码表 |
| 9 |
errorDesc |
错误消息 |
50字节 |
文字说明错误 |
签名原文: {"action":"CX","orderId":"api_test20160121154702900"}0FE8E43F53BB5848
提交：
{
"sign": "f168ccd4f353e3bf997a26a9e11282a0",
"agentAccount": "api_test",
"busiBody": {
"action": "CX",
"orderId": "api_test20160121154702900"
}
}
返回：
{
"action": "CX",
"agentAccount": "api_test",
"orderId": "api_test20160121154702900",
"chargeId": "146",
"agentBalance": 200,
"orderStatuText": "缴费成功",
"orderStatuInt": "16",
"orderPayment": 3,
"errorCode": 1,
"errorDesc": "操作成功"
}
3、代理商充值接口
该交易由接入方发起，提交的数据报中包含以下字段。
| 序号 |
字段名 |
字段含义 |
最大长度 |
说明 |
| 1 |
action |
交易指令码 |
2字节 |
固定值: CZ |
| 2 |
orderId |
定单号 |
20字节 |
接入方定单号，请确保唯一 |
| 3 |
chargeAcct |
充值账号 |
50字节 |
手机、固话号码，QQ号码等
固话和宽带需要带区号，但不要分隔符。
如 075588889999 |
| 4 |
chargeCash |
充值金额 |
5字节 |
整数金额 以元为单位 话费必填 |
| 5 |
flowCash |
流量充值金额 |
5字节 |
整数金额 以元为单位 流量必填 |
| 6 |
chargeType |
充值类型 |
2字节 |
0:手机充值 1:流量充值 2:固话充值 3:宽带充值
4:QQ|游戏充值 5:水电气缴费 6:加油卡充值 |
| 7 |
flowPackageType |
流量包类型 |
1字节 |
（*仅流量充值需要）
0：国内月包 1：省内月包 2：国内日包 3：省内日包
4：红包 5：国际流量 6：国内季包 7：省内季包
8： 闲时包省内 9：闲时包全国 10：小时包省内
11：小时包全国 12：2天包省内 13：2天包全国
14：3天包本省内 15：3天包全国 16：5天包省内
17：5天包全国 18：7天包省内 19：7天包全国
20：20天包省内 21：20天包全国 22：半年包省内
23：半年包全国 24：月末安心包全国
注：不传默认为0
|
| 8 |
flowPackageSize |
流量包规格 |
10字节 |
流量包大小，以M为单位；
如 500M，请传入整数500，1G请传入整数1024，2G-2048，3G-3072，4G-4096，依此类推。 |
| 9 |
qqProvince |
QQ 省份 |
10字节 |
例如 广东省、福建省 |
| 10 |
chargeAmount |
充值数量 |
5字节 |
整数 QB/QD充值数量 会员月数
* chargeType={4,5}需要提交, |
| 11 |
productSn |
产品代码 |
6字节 |
Q币:755001 Q点:755002
联调时由服务方提供各项目代码
chargeType={4,5}需要提交， chargeType=1 时特殊包需要传入如（三日包编码、七日包编码等）。 |
| 12 |
ispName |
运营商 |
- |
移动|联通|电信|广电|石化|石油
充值固话、宽带、加油卡时必填 |
| 13 |
retUrl |
回调地址 |
100字节 |
交易结果回调地址，不需回调者请留空；使用UrlEncode或者由json转义。
回调字段参照第4节
|
代理商充值返回数据格式：
| 序号 |
字段名 |
字段含义 |
字段长度 |
说明 |
| 1 |
action |
交易指令码 |
2字节 |
固定值: CZ |
| 2 |
agentAccount |
商户账号 |
1-20字节 |
原值返回 |
| 3 |
orderId |
定单号 |
1-20字节 |
原值返回 |
| 4 |
chargeId |
交易流水号 |
1-20字节 |
交易流水号 |
| 6 |
errorCode |
错误代码 |
4字节 |
参照错误代码表 |
| 7 |
errorDesc |
错误消息 |
50字节 |
文字说明错误 |
*此处返回数据中的成功仅代表提交成功，缴费是否成功请调用“定单查询接口”查询定单状态。
样例：
定单号:api_test20160121011731159
充值号码:13907550000
充值金额:50.00 (移动流量1G)
签名原文：
{
"action": "CZ",
"orderId": "api_test20160526142659562",
"chargeAcct": "13800138000",
"chargeType": 1,
"flowCash": 50,
"flowPackageType": 0,
"flowPackageSize": 1024,
"ispName": "移动",
"chargeAmount": 1,
"retUrl": "http%3A%2F%2Fretback.sohan.hk%2Fcallbacktest"
}0FE8E43F53BB5848
提交：
{
"sign": "8ef8b7468a2faf7d8cb41d342002baf3",
"agentAccount": "api_test",
"busiBody": {
"action": "CZ",
"orderId": "api_test20160526142659562",
"chargeAcct": "13800138000",
"chargeType": 1,
"flowCash": 50,
"flowPackageType": 0,
"flowPackageSize": 1024,
"ispName": "移动",
"chargeAmount": 1,
"retUrl": "http%3A%2F%2Fretback.sohan.hk%2Fcallbacktest"
}
}
返回:
{
"action": "CZ",
"agentAccount": "api_test",
"orderId": "api_test20160526142659562",
"chargeId": 203,
"errorCode": 1,
"errorDesc": "操作成功"
}
4、回调通知详情
定单交易结果将主动推送到您的回调地址上，回调地址在定单提交接口中提交retUrl字段；商户接收到回调通知后，需要应答，在无应答时服务器将多次发送回调。
回调通知应答内容为大写字母 OK； 不需要其他其他任何字符。
回调通知字段：
| 序号 |
字段名 |
字段含义 |
字段长度 |
说明 |
| 1 |
Action |
交易指令码 |
2字节 |
固定值: CX |
| 2 |
AgentAccount |
商户账号 |
1-20字节 |
原值返回 |
| 3 |
Agentbalance |
商户余额 |
1-20字节 |
商户当前余额 |
| 4 |
Orderid |
定单号 |
1-20字节 |
原值返回 |
| 5 |
Chargeid |
交易流水号 |
1-20字节 |
交易流水号 |
| 6 |
Orderstatu_int |
定单状态代码 |
1-2字节 |
定单状态与定单状态代码意义相同，
定单状态用于人工阅读，
定单状态代码便于程序识别。
0：等待处理 1：暂停处理
2：正在处理 6：正在缴费
11：处理成功 16：缴费成功
20：取消处理 21：处理失败
26：缴费失败 99：冻结 |
| 7 |
Orderstatu_text |
定单状态(文字说明) |
1-20字节 |
| 8 |
OrderPayment |
定单支付金额 |
1-20字节 |
交易成功定单的实际扣款金额 |
| 8 |
Errorcode |
错误代码 |
4字节 |
参照错误代码表 |
| 9 |
Errormsg |
错误消息 |
50字节 |
文字说明错误 |
返回样本数据串：
Action=CX&AgentAccount=api_test&Agentbalance=98981.00&Orderid=SH2009_05150001&Chargeid=2893131209&Orderstatu_int=16&Orderstatu_text=缴费成功&OrderPayment=3.00&Errorcode=0000&Errormsg=&Sign=59976d41950c16007e35a2886203564f
Sign的校验：MD5（Orderid=SH2009_05150001&Chargeid=2893131209&Orderstatu_int=16&Errorcode=0000&Password=0FE8E43F53BB5848）
四、错误代码对照表
| errorCode |
errorDesc |
出错原因 |
发生接口 |
| 1 |
操作成功 |
|
* |
| -100 |
账户不存在 |
agentAccount字段错误 |
* |
| -101 |
sign字段错误 |
密钥不对或者是MD5值错误 |
* |
| -102 |
账户被暂停使用 |
账户已经被冻结不能使用 |
* |
| -103 |
无API接口权限 |
ShtVer字段错误 |
* |
| -201 |
定单号不存在 |
查询的Orderid无效
*** 请使用原订单号再次提交。
*** 最后一次提交充值的30分钟之后再查询结果为【-201】才能处理失败。 |
查询接口 |
| -200 |
定单号不能为空 |
查询定单时未提交定单号 |
查询接口 |
| -301 |
IP错误 |
超出绑定的IP地址范围 |
充值接口 |
| -302 |
账户没有交易权限 |
账户交易权限被关闭 |
充值接口 |
| -303 |
充值号码为空 |
没有提交chargeAcct |
充值接口 |
| -304 |
定单号为空 |
没有提交orderId |
充值接口 |
| -305 |
账户余额不足 |
预存款不足本次定单交易 |
充值接口 |
| -310 |
定单号重复 |
提交的定单号已经存在，本次未生成新订单，请使用查询接口获取订单状态。 |
充值接口 |
| -990 |
指令错误 |
action字段不正确 |
* |
| -(991-998) |
未知错误 |
暂未明确定义的错误 |
* |
| -999 |
报文错误 |
未提交 busiBody |
* |
|
|
|
|
五、Java/C# 充值请求Demo
http://faq.sy666.com:82/index.php?View=entry&EntryID=78
技术支持联系方式：
网站：http://www.sy666.com
在线支持：http://Faq.sy666.com:82
QQ： 2881399287
E_mail：jianglong.li@sohan.hk
更新历史:
2015-11-15 多业务API接口 JSON版本
