炫捷--API文档

一、订单提交接口

1、调用方式 (HTTP – POST)

话费订单提交地址：http://host:port/IXJCWICommitOrder/XJCommitOrderHF.aspx
流量订单提交地址：http://host:port/IXJCWICommitOrder/XJCommitOrderLL.aspx

2、请求参数:

参数名称	类型	必填	备注
szAgentId	String(16)	是	商户账号(需联系商务生成)
szOrderId	String(32)	是	商户平台自行生成的订单编号，保证唯一性(由字母或数字组成)
szPhoneNum	String(32)	是	充值号码
nMoney	Integer	是	充值金额话费产品单位为：元流量产品单位为：M
nSortType	Integer	是	运营商编码：见附录
nProductClass	Integer	是	1：手机 2：固话 3：宽带
nProductType	Integer	是	1：话费充值 200：全国统付 201：全国漫游包 202：省内本地包 2013：全国漫游季包 2016：全国漫游半年包 20112：全国漫游年包 2023：省内漫游季包 2026：省内漫游半年包 20212：省内漫游年包注： (200为全国三网流量，包含全国移动、全国联通、全国电信； 201为分省的全国可漫游流量； 202为分省的省内流量）
szProductId	String(16)	否	特定产品编码 (不参与校验，对接流量请忽略此参数) （由接口获取或商务提供，主要用于特定产品的充值）
szTimeStamp	DateTime	是	时间戳。用于判断过期响应，与炫捷服务器时间间隔5分钟内有效。格式:yyyy-MM-dd HH:mm:ss (例如：2016-01-01 07:23:00)
szVerifyString	String(32)	是	验证摘要串
szNotifyUrl	String(128)	否	完成结果回调通知地址（不参与签名）
szFormat	String(8)	否	结果返回格式: XML JSON

3、订单提交加密参数和顺序规则

szVerifyString=Md5(szAgentId=xxx&szOrderId=xxx&szPhoneNum=xxx&nMoney=xxx
&nSortType=xxx&nProductClass=xxx&nProductType=xxx&szTimeStamp=xxx&szKey=xxx) .ToLower()
32位标准Md5加密后小写(这里的xxx为具体的参数值)

4、订单提交请求参数示例

5、请求返回内容

参数名称	类型	备注
nRtn	Interger	返回状态
szOrderId	String(32)	充值请求的订单号
fNBalance	Decimal	结算后余额
fSalePrice	Decimal	该笔订单结算金额
szRtnCode	String(32)	返回码(以“返回状态”值为准)

6.返回内容示例

1) XML格式：


							<?xml version="1.0" encoding="UTF-8"?>  

							<return>  

								       <nRtn>0</nRtn>  

								       <szOrderId>YXTest20160607094841</szOrderId>  

								       <fNBalance>19323.8800</fNBalance>  

								       <fCredit>0</fCredit>  

								       <fSalePrice>7.2000</fSalePrice>  

								       <szRtnCode>OK_InitOrder</szRtnCode>  

							</return>

2) JSON格式：


							{    

							      	"nRtn":0,    

							      	"szOrderId":"YXTest20160607100125",    

							      	"fNBalance":19323.8800,    

							      	"fCredit":0,    

							      	"fSalePrice":7.2000,    

							      	"szRtnCode":"OK_InitOrder"    

							}

7.充值请求注意事项

1) 充值请求以炫捷科技服务器时间为准，时间戳差异超过1分钟则判定该次请求为过期请求。
2) 充值请求可以多线程并发提交。
3) 充值请求收到的结果为收单结果，收单成功不代表充值成功。
4) 充值请求的商户订单号由商户自行生成，订单号生成规则为字母或数字组合，商户订单号字符串长度建议为16-32位。如果商户订单号不符合生成规则（如：包含其他非法字符、订单号长度超长）造成的订单异常损失由商户自行承担。

8.返回状态码（nRtn）

返回码及描述	备注
0	提交成功
1000系统接口维护 1001时间戳错误 1003数据格式错误 1004加密错误 2001\2002号码或号段错误 2003黑名单号码 2020\2021\2022用户信息异常 6005\6006余额信息错误 2030\2031\2032产品配置错误 1006余额不足 2043通道配置异常 3001\3002扣款失败 2040 没有配置产品 2041 没有配置产品售价	直接处理为失败
3003\3004扣款错误（可能是订单号重复引起的） 2051\2050生成订单异常 999 系统异常	需要走查询请求确认

二、订单状态查询接口

1、HTTP POST (也可以通过Socket或WebServices )

话费订单查询地址：http://host:port/IXJCWIQueryOrder/XJQueryOrderHF.aspx
流量订单查询地址：http://host:port/IXJCWIQueryOrder/XJQueryOrderLL.aspx

2、请求参数:

参数名称	类型	必填	备注
szAgentId	String(16)	是	商户账号(需联系商务生成)
szOrderId	String(32)	是	充值请求时提交的订单号
szVerifyString	String(32)	是	验证摘要串
szFormat	String(8)	否	结果返回格式: XML JSON

3、订单状态查询加密参数和顺序规则

szVerifyString=Md5(szAgentId=xxx&szOrderId=xxx&szKey=xxx).ToLower()
32位标准Md5加密后小写(这里的xxx为具体的参数值)

4、订单状态查询请求参数示例

szAgentId=geniusyang&szOrderId=YXTest20160607100125
&szVerifyString=qwertyuioplkjhgfdsazxcvbnm123456&szFormat=XML
32位标准Md5加密后小写(这里的xxx为具体的参数值)

5、请求返回内容

参数名称	类型	备注
nRtn	Interger	返回状态。 999查单服务异常需要重新发起（不能判断为失败） 5001查单服务关闭需要人工查询（不能判断为失败） 5003参数错误（不能判断为失败） 5004加密串错误（不能判断为失败） 5010初始化(处理中) 5011处理中（处理中） 5012充值成功（成功）成功 5013充值失败（失败）失败退款 5019对账状态（处理中） 5005无此订单（无订单）提交订单2分后查询返回可失败或重新提交其余状态均不可处理为失败，需再次发起查询
szOrderId	String(32)	充值请求的订单号
fSalePrice	Decimal	该笔订单结算金额
szRtnCode	String(32)	返回码(以返回状态值为准)
szRtnMsg	String	备注字段，不参与签名

6.返回内容示例

1) XML格式：


							<?xml version="1.0" encoding="UTF-8"?>  

							<return>  

								       <nRtn>5012</nRtn>  

								       <szOrderId>YXTest20160603132137</szOrderId>  

								       <fSalePrice>7.2000</fSalePrice>  

								       <szRtnCode>OrdOK</szRtnCode>  

							</return>

2) JSON格式：


							{    

							      	"nRtn":5012,    

							      	"szOrderId":"YXTest20160603132137",    

							      	"fSalePrice":7.2000,    

							      	"szRtnCode":”OrdOK“,    

							}

7.充值请求注意事项

1) 查询请求必须要在订单请求提交时间2分钟后发起。在订单提交后30秒内未生成订单之前发起查询请求可能会无结果，但是不代表订单不存在。
2) 订单查询为明确成功和明确失败的订单可以对订单做最终处理，其余状态均不可自行处理为失败(处理中或初始化等生成状态的订单请处理为等待结果通知状态)。
3) 提交订单2分钟后调用查询接口返回无订单才可以失败或者再次提交。
4) 针对于成功状态的订单有异议的订单，请协商客服或运营商务处理。部分订单因为运营商入账延迟等问题出现的异常在运营商没有明确处理结果之前不可处理失败退款。

三、订单状态推送（回调）

我方主动将订单结果推送给客户，用以用户确认订单是否成功

1、推送请求方式（HTTP-POST）

2、回调通知参数:

参数名称	备注
szAgentId	商户账号(需联系商务生成)
szOrderId	商户平台自行生成的订单编号，保证唯一性(由字母或数字组成) 同一订单号同一天内提交只处理一次
szPhoneNum	手机号码
nDemo	面值：流量产品单位为：M 话费产品单位为：元例如：10M nDemo=10
fSalePrice	售价
nFlag	2成功 3失败
szRtnMsg	备注字段，不参数签名
szVerifyString	验证摘要串

3、推送加密参数和顺序规则

szVerifyString=Md5(szAgentId=xxx&szOrderId=xxx&szPhoneNum=xxx&
nDemo=xxx&fSalePrice=xxx&nFlag=xxx&szKey=xxx) .ToLower()
32位标准Md5加密后小写(这里的xxx为具体的参数值)

4、返回内容

回调信息成功接收后请返回文本“ok”

四、查询账户余额接口

1、HTTP - POST (也可以通过Socket或WebServices )

查询余额地址：http://host:port/IXJCWIQueryBalance/XJQueryBalance.aspx

2、请求参数:

参数名称	类型	必填	备注
szAgentId	String(16)	是	商户账号(需联系商务生成)
szVerifyString	String(32)	是	验证摘要串
szFormat	String(8)	否	结果返回格式: XML JSON

3、余额查询参数和顺序规则

szVerifyString=Md5(szAgentId=xxxx&szKey=xxxx).ToLower()
32位标准Md5加密后小写(这里的xxx为具体的参数值)

4、余额查询请求参数示例

szAgentId=geniusyang&szVerifyString=qwertyuioplkjhgfdsazxcvbnm123456&szFormat=XML

5、请求返回内容

参数名称	类型	备注
nRtn	Interger	返回状态。 0为查询余额成功，其余为错误或异常 6003提交参数有误 6004加密有误
szAgentId	String(16)	商户账号。
fBalance	Decimal	帐号余额。
fCredit	Decimal	帐号信用额度。
szRtnCode	String(32)	返回码(以返回状态值为准)

6.返回内容示例

1) XML格式：


							<?xml version="1.0" encoding="UTF-8"?>  

							<return>  

								       <nRtn>0</nRtn>  

								       <szAgentId>geniusyang</szAgentId>  

								       <fBalance>20009.9350</fBalance>  

								       <fCredit>0</fCredit>  

								       <szRtnCode>OK_QryUsrBlnc</szRtnCode>  

							</return>

2) JSON格式：


							{    

							      	"nRtn":0,    

							      	"szAgentId":"geniusyang",    

							      	"fBalance":20059.7100,    

							      	"fCredit":0,    

							      	"szRtnCode":"OK_QryUsrBlnc",    

							}

7.充值请求注意事项

1) 余额查询供用户查询最新的实时余额及固定授信额度，可用金额=用户余额+固定授信额度
2) 余额查询不能频繁提交，每分钟只受理一次请求。
3) 余额查询不可多线程提交。
4) 余额查询的结果可能会收到处理中订单、退款订单、调账订单、余额加款、余额扣款等因素影响，与实际账户余额有差异，以最终静态对账余额为准。
5) 不允许以余额变化为条件判断订单状态。

六、附录

运营商编码

编码	运营商	备注
1	移动
2	联通
3	电信
4	虚商
5	爱施德
6	迪信通
7	分享
8	凤凰
9	话机世界
10	苏宁
11	天音
12	蜗牛
13	星美
14	中麦
15	远特
16	银盛
17	朗玛
18	海航
19	青牛
20	红豆
21	民生
22	乐语
23	中兴
24	国美
25	日日顺
26	中期
27	长江
28	用友
29	三五互联
30	优酷
31	华翔
32	连连
33	中邮
34	鹏博士
35	京东
99	阿里
101	电费
102	水费
103	广电有线电视
104	中石化
105	中石油
41	其它
106-199	201-999

下载Demo

一、订单提交接口

1、调用方式 (HTTP – POST)

2、请求参数:

3、订单提交 加密参数和顺序规则

4、订单提交 请求参数示例

5、请求返回内容

6.返回内容示例

7.充值请求注意事项

8.返回状态码（nRtn）

二、订单状态查询接口

1、HTTP POST (也可以通过Socket或WebServices )

2、请求参数:

3、订单状态查询 加密参数和顺序规则

4、订单状态查询 请求参数示例

5、请求返回内容

6.返回内容示例

7.充值请求注意事项

三、订单状态推送（回调）

1、推送请求方式 （HTTP-POST）

2、回调通知参数:

3、推送 加密参数和顺序规则

4、返回内容

四、查询账户余额接口

1、HTTP - POST (也可以通过Socket或WebServices )

2、请求参数:

3、余额查询 参数和顺序规则

4、余额查询 请求参数示例

5、请求返回内容

6.返回内容示例

7.充值请求注意事项

六、附录

运营商编码

3、订单提交加密参数和顺序规则

4、订单提交请求参数示例

3、订单状态查询加密参数和顺序规则

4、订单状态查询请求参数示例

1、推送请求方式（HTTP-POST）

3、推送加密参数和顺序规则

3、余额查询参数和顺序规则

4、余额查询请求参数示例