天宏一卡通支付接口说明文档V.doc

天宏一卡通支付接口说明文档V

———————————————————————————————— 作者：
———————————————————————————————— 日期：

9

个人收集整理 勿做商业用途
1 引言
1.1 编写目的
文档历史
修订日期
修订内容
修订版本
修订人
2010-7-１
创立
１.0.1
ｌvzhe
2０10－７-14
修改支付金额为可选参数。
1.０.2
lvzhｅ
本文档说明了如何通过网关系统和天宏公司一卡通游戏充值系统进展对接。

2 协议概述
2.1 协议列表
协议名称
说明
销售协议
充值一卡通的协议
2.2 协议的交互逻辑

商家
华彤

销售请求

销售结果

3 销售协议
3.1 协议说明
协议采用ＨTTＰ协议,经销商将请求报文pｏst或get到天宏的一卡通充值的8０端口：
正式地址:
支付地址:ｈttp:/／port.27３９9．com／gaｔewaｙ/ＥCaｒd_ＰayGａte.do
单笔查询地址:ｈｔtp:／/port．27３９9．com/gaｔｅｗay/ECarｄ_QueryＧate＿Sｉngle.do
批量查询地址:hｔtp：／/ｐort.27３99.ｃom/ｇaｔeway/ECard_QueryGate．do

url例如:
ｈttｐ：//ｐort．2７399.cｏm／gａｔｅｗａy/ＥCard_PａyＧate.do?useｒname=＊**&producｔid=***＆cknｕm＝＊＊*＆kahao1＝***＆ｍima1=**＊ ＆buｙｎｕm=***　&ｏrdｅｒNｕｍ＝*＊*＆adｄｉｔiｏn=＊*＊&returnUrl=＊**　&md５toselｆ=＊**

hｔtp:／/pｏrt．273９9.ｃom/gatｅway/ECaｒd_QueryＧａｔｅ＿Ｓinｇlｅ.do?usｅrName=***&orｄｅｒＮｕm=*＊＊&md5ｔoｓｅlf＝＊**

hｔtｐ:/／port.27399 /gatewａｙ／ＥCard＿ＱuｅrｙGatｅ．dｏ?usｅrＮame＝＊**&ｐrｏｄuctID=＊*＊&ｅCardＮｕm=**＊ &buｙNum=***&orderNum=***＆ｓtａrtDａte=**＊&eｎdDaｔe=*＊*&ip=*＊*&ｐageＣounｔ=＊*＊＆ｐageInｄex=***&ｍd５toself＝***

测试地址：
支付地址：hｔｔp://222．２２2.59.248／ECardPay／gatｅway /ＥCａrd＿PayＧａte.ｄo
单笔查询地址: :／/２２２.２22.59．2４8/ECaｒdPay／gaｔeway / ECａrd_QｕeｒyGate_Siｎｇle.do
批量查询地址:htｔｐ://２2２.222.５9.248/ECarｄＰaｙ／ｇａｔewａｙ　/ ECard_QｕeryＧａｔe．dｏ

3.1.1 支付接口调用说明
支付接口参数说明:
输入参数
数据类型
说明
是否必填
usｅrnaｍｅ
vaｒchａr(2０)
商户名
Ｙ
proｄｕctｉd
Ｉｎｔ
产品类型，请和公司申请
Y
cknum
Int
一卡通张数
Y
kahaｏ1
mima1
kahao2
miｍa2
＊
＊
＊
vａｒchａr(50)
一卡通卡号密码
(最多支持5张一卡通组合充值支付〕
Y
buｙnum
Int
购置数量(按元计算,1=１元)

orderNum
ｖarchar(50)
商户订单号
Y
ａddｉtion
varcｈaｒ〔50)
附加信息

retuｒnUrl
vａrchar(2００)
回调地址

mｄ5toself
Int
　 　　　数字签名
Y
ﻩ

ﻩ调用说明：
1. 所有字段中不能包含 “&〞 和 “＝〞
2. ｕsernａme: 商户名,例如 huaｔonｇ
3. productiｄ:表示产品类型，真实产品IＤ请和天宏公司索要。
4. cknｕm：本次充值所提交的一卡通数量，请注意和ｋaｈao、mimａ字段要保持一致。
5. ｋahao\mima:所提交的一卡通卡号密码,形式为kaｈao1、ｋａhao2…….miｍa1、mima２……,，其中密码为MＤ５(3２位)加密后的结果卡号密码提交前请务必请转换成大写。
6. buyｎum：充值数量　　 表示充值1面值卡的张数,取值范围[1,　５00]。可选参数，不传时默认全额支付〔支付所传一卡通的所有余额〕。
7. oｒdeｒＮｕm:　商户订单号
8. ａddiｔｉｏｎ:　附加信息
9. ｒｅturｎＵrl： 回调地址,用于异步调用时的回调。
10. md5toself为按顺序对交易信息的MD5加密签名的32位字符串：
md5tosｅlf =ｍd5(username=**＊＆ｐrｏｄuctｉd＝***&cｋnｕm=＊*＊＆kａhao1＝＊**&ｍima1=***　&buynｕm＝*＊* ＆orderNｕm=*＊*&addｉtioｎ=＊**&ｒeｔurnUrｌ=＊** |｜enc_kｅｙ) 。
l 可选参数如果不传的话,不能包含在加密串中。
l 其中ｅnc_key为双方约定的kｅy,用于验证交易的合法性，请和天宏公司申请。

3.1.2 支付接口返回结果说明

返回结果是ｘｍl格式数据字符串
<root>
<staｔe>
  <codｅ>1<／coｄe>　
  <ｍsｇ>成功！</mｓg>
　 ＜moneｙ＞１0<／moｎey>
　　</ｓtatｅ>
</ｒoｏt>

充值结果代码
结果说明
0
未知异常
1
成功
-１
参数验证异常
-２
一卡通验证异常
-３
账户验证异常
-４
支付类型验证异常
-5
订单验证异常
-6
支付操作异常

3.1.3 查询接口调用说明

1. 单笔查询接口参数说明：
输入参数
数据类型
说明
默认值
是否必填
userNａme
ｖaｒｃｈar(20)
商户名

Y
orｄeｒＮuｍ
vaｒchar(50)
商户订单号

Y
md5toｓｅｌf
Int
　 　 数字签名

Y

ﻩ调用说明：
1. 所有字段中不能包含 “&〞　和 “＝〞
2. usｅrNａme: 商户名,例如 hｕatｏng
3. orｄｅrNuｍ: 商户订单号
4. md5ｔoselｆ为按顺序对交易信息的ＭD5加密签名的32位字符串：
md5ｔｏｓelｆ =md5(userName=***&ordｅｒＮum=***|｜enc＿key〕　。
l 其中eｎc_key为双方约定的keｙ,用于验证交易的合法性，请和天宏公司申请。

2. 批量查询接口参数说明:
输入参数
数据类型
说明
默认值
是否必填
usｅrＮame
varcｈar(20)
商户名

Y
prodｕcｔID
Ｉnt
产品类型,请和公司申请
0

eCardNuｍ
vａrcｈar(5０〕
一卡通卡号

bｕｙＮum
Int
购置数量〔按元计算,1=1元〕
0

orderNuｍ
varcｈar(５0)
商户订单号

stａrtＤate
varｃhａr〔５0)
开场时间

ｅndＤate
varchar(５0)
截止时间

ip
vaｒcｈａr(50)
支付ip地址

pageCｏunt
ｉｎt
每页数量
１00(暂定)

pａgeIndex
iｎｔ
页码
１

mｄ5toselｆ
Inｔ
　 　 数字签名

Y

ﻩ调用说明:
5. 所有字段中不能包含 “&〞 和 “＝〞
6. uｓerName:　商户名，例如　 ｈuatｏng
7. productＩD:表示产品类型，真实产品ID请和天宏公司索要。
8. eCaｒdNuｍ:所提交的一卡通卡号。
9. ｂuyNｕm：充值数量　 表示充值１面值卡的张数，取值范围[1, ５00]
10. orderＮｕm: 商户订单号
11. stａrｔＤate: 开场时间
12. eｎdDate:　截止时间
13. ｉp:　支付时的ip地址
14. ｐagｅCount:每页记录数
15. pageＩndｅx:当前页码
16. md5toself为按顺序对交易信息的MD5加密签名的３2位字符串：
md５toｓelf =ｍd５〔userＮaｍe=***&pｒoｄuctID=**＊&eCａrｄNum=*＊＊　&bｕyNｕm=*** ＆oｒderNｕｍ=*＊*&starｔDａtｅ=***&ｅndDaｔe＝*** &ｉｐ＝*＊*＆pａｇeCｏunt=＊＊＊&pａgeIｎdeｘ=*＊*||enｃ_key〕 。
l 可选参数如果不传的话，不能包含在加密串中。
l 其中ｅnc_key为双方约定的key,用于验证交易的合法性,请和天宏公司申请。

3.2 返回结果说明

返回结果是Ｘmｌ格式数据字符串
1． 单笔查询：
<roｏｔ>
<state>
  ＜coｄe＞１</code>
  <ｍｓg>查询成功！<／msg>
 　<／state>
<items＞
</ｉteｍs>
<md5Keｙ>＜/md５Ｋey＞
<／ｒoot>
2． 批量查询
<root>
<stａtｅ>
  <ｃode>１</coｄe＞
  ＜msg>查询成功！</ｍｓｇ＞　
  </ｓｔａte>
<paｇｅ>
  ＜ｔｏtalCount＞４</tｏtａlCｏunt＞
  ＜perPageＣｏｕｎt>30＜/pｅrPaｇeCoｕｎt>
  <pａgeIndeｘ>1＜／pageＩndex>
　<ｔotaｌＰage>１<／ｔｏtａlＰaｇe>
</page>
<iｔems>
</itｅms＞
＜/root＞

1. Codｅ: 返回值编码
2. Ｍｓg： 返回信息
3. ｔotalＣouｎt:　记录总数
4. perPageCｏｕｎt: 每页记录数
5. pａgeIndｅｘ:　当前页码
6. md5Key： mｄ５加密的数据信息。用于单笔查询中的平安认证。
规那么:
ｍd５Key　= mｄ５(uｓｅrNaｍe＝***&buyNum＝***＆ｏｒｄerNum＝*＊*＆pａyDaｔe=＊** &codｅ=*＊*|｜enｃ_key〕
其中ｅnc＿keｙ为双方约定的key,用于验证交易的合法性，请和天宏公司申请。
7. items： 数据明细节。用于显示数据的详细信息。例如:
<itｅｍ>
  <useｒNamｅ>ｔｅｓｔ＜/ｕserNamｅ>
  <ｐroductID>１</proｄuctID>　
  <eＣardＮｕm>GＣ０7０610０328<／ｅＣarｄNum>　
  <bｕyNum>1＜/buyNum＞
  <payＤate>2０1０/7/７ 1６:1２:2９＜/ｐayDaｔe>
  <ordeｒNｕm>11</ｏｒderNum＞
  <addｉｔｉon＞aaa＜/aｄdition>　
  ＜rｅtｕrnＵrｌ＞ ://localhoｓt:303９/porｔ27399/gatｅway/RｅｔurnPａge．asｐx</rｅｔurｎＵrl＞　
  </ｉtem>

查询结果代码
结果说明
1
成功
0
未知异常
-1
系统检测到不平安的字符!
-2
用户名不能为空!
-3
参数类型错误!
－４
md5串格式错误！
-5
用户验证失败！
-6
ip地址校验失败!
-７
mｄ5校验失败!