ChinaPay收付捷平台_批量代扣接口文档V15

1、 ChinaPay收付捷平台批量代扣接口文档（Version 1.5）上海银联电子支付服务有限公司地址：上海浦东新区东方路800号 宝安大厦29楼-30楼 (200122)Tel: (86-021)60872088 Fax: (86-021)60872000 Website: http:/www.ChinaP©Copyright 2014 ChinaPay e-Payment Service Co.,Ltd. All rights reserved修订历史记录版本号修改人时间修改内容备注V1.0黄旭婷2012-04-20整理原有批量代扣接口说明，形成新版代扣商户批量上传接口规范V1.

2、0V1.1黄旭婷2012-06-05增加3.4节批量代扣文件查询接口说明；修改4.1节订单号为定长，16位。V1.2胡建林2012-08-08修改“2.2.1”章节的举例中的订单号。V1.3胡建林2012-11-20修改测试环境地址的IP，由“9”修改为“45”。V1.4张胜2014-04-01修改各接口提交地址V1.5张胜2015-01-20增加附录4.6交易状态码表目录1.概述42.批量代扣交易流程描述42.1批量代扣交易流程42.2批量文件上传接口流程52.2.1批量代扣文件的生成52.2.2对需要上传的字段签名52.2.3表单上传52.

3、2.4返回报文验签53.批量代扣接口描述53.1批量代扣文件上传接口53.1.1概要说明53.1.2交易请求数据示例63.1.3交易请求URL63.1.4上传文件数据内容描述63.1.5Chinapay返回应答数据73.2回盘文件通知接口83.2.1Chinapay通知数据83.2.2通知商户的URL规范83.3回盘文件内容下载接口93.3.1交易请求数据示例93.3.2交易请求URL93.3.3表单上传数据内容描述93.3.4Chinapay应答数据103.4批量代扣文件查询接口113.4.1交易请求数据示例113.4.2交易请求URL113.4.3表单上传数据内容描述113.4.4Chin

4、apay返回应答数据124.附录134.1商户给Chinapay的代扣交易批量文件134.2代扣回盘文件144.3商户交易请求数据签名和验签说明164.3.1.核心文件清单164.3.2.方法说明164.3.3.使用示例代码174.4使用Zip压缩字节流示例184.5各银行测试卡BIN规则194.6交易状态码表191. 概述本文档对商户接入批量上传代扣功能通信的接口进行了详细的描述，商户端程序如需要进行开发可以此文档为依据。接口传输的所有参数（特别是一些中文，非ASCII字符集字符）都使用UTF-8进行编码，签名验签接口也都使用UTF-8进行编码。目前该接口仅支持使用JAVA语言进行开发。2.

5、 批量代扣交易流程描述2.1 批量代扣交易流程2.2 批量文件上传接口流程2.2.1 批量代扣文件的生成交易信息请参考附录4.1中的代扣文件内容格式规范。上传的批量代扣信息格式举例：808080080988041|092007|5|500020120413|0000000000000001|0103|0|6228401111111111111|姓名|011000|用途|私有域20120413|0000000000000002|0103|0|6228401111111111111|姓名|011000|用途|私有域20

6、120413|0000000000000003|0103|0|6228401111111111111|姓名|011000|用途|私有域20120413|0000000000000004|0103|0|6228401111111111111|姓名|011000|用途|私有域20120413|0000000000000005|0103|0|6228401111111111111|姓名|011000|用途|私有域2.2.2 对需要上传的字段签名见附录4.3的商户交易请求数据签名和验

7、签说明2.2.3 表单上传见第3.1节批量代扣文件上传接口说明2.2.4 返回报文验签见附录4.3的商户交易请求数据签名和验签说明3. 批量代扣接口描述33.1 批量代扣文件上传接口3.1.1 概要说明该接口定义商户交易的数据传输，商户通过该接口进行交易。接口基于http post方式提交交易参数和数字签名，处理完毕通过http post方式返回带签名的处理结果。3.1.2 交易请求数据示例<form name="WithBatch" action="9/dac/BatchCutUTF8" method=&quo

8、t;post"><input type="hidden" name="merId" value="<%=merId%>"><input type="hidden" name="fileName" value="<%=fileName%>"><input type="hidden" name="fileContent" value="<%=fileCon

9、tent%>"><input type="hidden" name="chkValue" value="<%=chkValue%>"><input type="submit" name="sub" value="提交"></form>3.1.3 交易请求URL生产：测试：9/dac/BatchCutUTF83.1.4 上传文件数据内容描述No参数名说明长度备注1merId

10、商户号Char(15)2fileName文件名Varchar(40)txt格式MERID_YYYYMMDD_XXXXXX_Q.txtMERID: 15位的商户号YYYYMMDD: 商户生成文件的日期共8位(上传当天日期)XXXXXX: 6位的批次号3fileContent文件内容varchar(1024*1024*10)最大不超过4万笔使用Zip压缩后的字节流，并转换为Base64编码格式提交（方法参考附录4.4示例）格式见附录4.1“商户给Chinapay的代扣交易批量文件”4chkValue签名密文Char(256)签名明文为：merId + fileName + tmpCheck（tmp

11、Check为原始文件内容的MD5摘要，摘要后内容需转换为Asc码，具体代码见4.3.3节） 调用netpayclinet.jar包中方法Sign (详细内容参见4.3.2章节)3.1.5 Chinapay返回应答数据No参数名说明长度备注1responseCode应答码Char(4)20FM表示批量代扣文件上传成功其余表示失败2message应答描述Varchar(40)UTF-8格式中文应答信息3chkValue签名密文Char(256)对返回字串的签名。签名字串明文为：responseCode=20FM&message=文件上传成功&chkValue=cp应答数据示例l 成

12、功应答responseCode=20FM&message=文件上传成功&chkValue=X256位Xl 失败应答responseCode=2094&message=重复交易&chkValue=X256位X先对验签明文进行MD5摘要,然后将摘要内容转换为Asc码。具体验签方法请参考4.3.3节中验证签名示例代码。3.2 回盘文件通知接口3.2.1 Chinapay通知数据No参数名说明长度备注1responseCode响应码Char(4)1001 回盘文件生成成功，其余为失败2message描述Varchar(120)UTF-8格式中文应答信息3merId商户号

13、Char(15)4orFileName原始文件名Varchar(40)格式为：MERID_YYYYMMDD_XXXXXX_Q.txt5fileName下载文件名Varchar(40)格式为：MERID_YYYYMMDD_XXXXXX_P.txt6chkValue签名密文Char(256)验签明文：responseCode+message+merId+orFileName+ fileName先对验签明文进行MD5摘要,然后将摘要内容转换为Asc码。具体验签方法请参考4.3.3节中验证签名示例代码。3.2.2 通知商户的URL规范1. 商户需提供接收回盘通知的URL路径（http，不要是https

14、），CP对商户号和通知路径进行绑定，绑定成功后以URL形式通知。2. 该页必须返回包含ChinapayOk字样（注意大小写），表明商户已收到通知。3.3 回盘文件内容下载接口3.3.1 交易请求数据示例<form name="Down" action="9/dac/DownFileExe" method="post"><input type="hidden" name="merId" value="<%= merId %>

15、;"><input type="hidden" name="orFileName" value="<%= orFileName %>"><input type="hidden" name="fileName" value="<%= fileName %>"><input type="hidden" name="chkValue" value="<%=

16、chkValue %>"><input type="submit" name="sub" value="提交"></form>3.3.2 交易请求URL生产：测试：9/dac/DownFileExe3.3.3 表单上传数据内容描述No参数名说明长度备注1merId商户号Char(15)2orFileName原始文件名Varchar(40)txt格式MERID_YYYYMMDD_XXXXXX_Q.txtMERID: 15位的商户号YYYYMMDD: 商户生

17、成文件的日期XXXXXX: 6位的批次号3fileName下载文件名Varchar(40)txt格式MERID_YYYYMMDD_XXXXXX_P.txtMERID: 15位的商户号YYYYMMDD: 商户生成文件的日期XXXXXX: 6位的批次号以上字段同原始文件名对应4chkValue签名密文Char(256)签名明文merId + orFileName + fileName先对签名明文进行MD5摘要,然后将摘要内容转换为Asc码。具体签名方法请参考4.3.3节中签名示例代码。3.3.4 Chinapay应答数据 应答数据内容描述No参数名说明长度备注1merId商户号Cha

18、r(15)2orFileName原始文件名Varchar(40)txt格式MERID_YYYYMMDD_XXXXXX_Q.txt3fileName下载文件名Varchar(40)txt格式MERID_YYYYMMDD_XXXXXX_P.txt4fileData文件内容Varchar(1024*1024*10)Base64编码形式5chkValue签名密文Char(256)验签明文见下方说明 返回形式1.回盘文件下载成功返回报文：merId=value&orFileName=value&filename=value&fileData=value&ch

19、kValue=value验签明文：对fileData进行解压缩后得到的文件内容。例如：merId=808080080988041&orFileName=808080080988041_20120413_143938_Q.txt&fileName=808080080988041_20120413_143938_P.txt&fileData=eJzNjj0KwkAQhXvBu7zZn2T3bq8wnREDAVMKQVLEM8TrZDd4C0fE0laWmWJ4883wBQQt7RgCnFCcjTbQ0wPY7wzEaGz5HT57CCEAwcoIYgUvtUTAuloM87

20、lJ3W1dljRfUt8pSivKKxIianirz6j34Dbcn4eB29zka5vG8Z0K18eU2ykf+3Qa+VvClCBhS5BwJUj4/0m8AO4XA7Y=&chkValue=X256位X2.没有查到回盘文件返回报文：responseCode=20FK&message=未查到有效交易&chkValue= X256位X验签明文：responseCode=20FK&message=未查到有效交易&chkValue= 验签方式 先对验签明文进行MD5摘要,然后将摘要内容转换为Asc码。具体验签方法请参考4.3.3节中验证签

21、名示例代码。3.4 批量代扣文件查询接口3.4.1 交易请求数据示例<form name="QueryFile" action="9/dac/FileStatQuSer" method="post"><input type="hidden" name="merId" value="<%= merId %>"><input type="hidden" name="file

22、Name" value="<%= fileName %>"><input type="hidden" name="chkValue" value="<%= chkValue %>"><input type="submit" name="sub" value="提交"></form>3.4.2 交易请求URL生产：测试：9/dac/FileStat

23、QuSer另外需要额外说明的是查询服务器采用了流量控制的方式来进行服务，需要满足以下条件：只对开放查询功能的商户指定的IP地址访问的请求响应，并且前后两次查询间隔在系统设置的时间间隔（默认设置为间隔50秒）之外的查询请求才被接纳，否则会报错(错误代码20E9)。商户开通查询功能时需要提供查询使用的服务器的公网IP地址以及商户号。3.4.3 表单上传数据内容描述No参数名说明长度备注1merId商户号Char(15)2fileName上传文件名Varchar(40)txt格式MERID_YYYYMMDD_XXXXXX_Q.txtMERID: 15位的商户号YYYYMMDD: 商户生成文件的日期X

24、XXXXX: 6位的批次号3chkValue签名密文Char(256)签名明文merId + fileName先对签名明文进行MD5摘要,然后将摘要内容转换为Asc码。具体签名方法请参考4.3.3节中签名示例代码。3.4.4 Chinapay返回应答数据No参数名说明长度备注1responseCode应答码Char(4)20FM表示商户上传文件成功20FK表示未找到该文件记录20E9表示IP地址不允许，或者访问间隔过短20GK表示文件校验失败20FN表示代扣已接受20GM表示所有数据都是无效数据20GN表示回盘文件已生成20GQ表示文件数据过大2message应答描述Varchar(40)UT

25、F-8格式中文应答信息3chkValue签名密文Char(256)对返回字串的签名。签名字串明文为：responseCode=20FN&message=代扣已接受&chkValue=cp应答数据示例l 成功应答responseCode=20GN&message=回盘文件已生成&chkValue=X256位Xl 失败应答responseCode=20FL&message=签名失败&chkValue= X256位X先对验签明文进行MD5摘要,然后将摘要内容转换为Asc码。具体验签方法请参考4.3.3节中验证签名示例代码。4. 附录44.1 商户给Ch

26、inapay的代扣交易批量文件文件内容（特别是中文字段）必须使用UTF-8编码格式定义。文件格式: 文本文件(.txt)文件命名规范：MERID_YYYYMMDD_XXXXXX_Q.txtMERID: 15位的商户号YYYYMMDD: 商户生成文件的日期，共8位XXXXXX: 6位的批次号 Q: 代扣文件文件内容格式规范：文件内容包括文件头和文件体。文件头与文件体由回车换行符分割。文件头: 文件的第一行，包含：商户号，批次号，总笔数，总金额，各项用“|”分割。如下表所示：“12345000000001|000001|100|90000”No数据项内容说明1商户号12345000000001Ch

27、inaPay分配给商户的唯一标识 定长15位2批次号000001商户上传文件的批次号 定长 6位3总笔数1000当前文件中，交易明细总数， 变长5位，建议每个批次不超过1000笔，最多不能超过5000笔。4总金额90000交易总金额，以分为单位 最长长度15位文件体: 文件体存放的是具体的交易数据，一行代表一笔交易记录。在每一行交易记录中，交易所需的各项都用“|”隔开，具体说明见下表。每一行交易明细中的各项尽可能不要有空格存在。No项目描述格式长度是否必须备注1商户日期数字定长，8位必须标志该笔交易在商户端发生的日期，与文件名日期保持一致 2订单号数字定长，16位必须交易记录流水号，同商户日期

28、一起唯一标识文件中的一笔交易3开户行代号数字定长，4位必须如中国工商银行代号：01024卡折标志数字定长，1位必须表示随后记录为卡号或存折号(0:卡,1:折)5卡号/折号字符变长，25位必须银行卡号或者存折号码6持卡人姓名字符变长，40位必须可直接填写中文名7身份类型字符定长，2位必须证件类型，定义如下：身份证01 , 军官证02 ,护照03 , 户口簿04 , 回乡证05 , 其他068证件号字符变长，25位必须证件号码9金额数字变长，12位必须（整型）整数，以分为单位 10用途字符变长，25位必须扣款用途11私有域字符变长，60位必须商户专用4.2 代扣回盘文件文件格式: 文本文件(.tx

29、t)文件命名规范：MERID_YYYYMMDD_XXXXXX_P.txtMERID: 15位的商户号YYYYMMDD: 商户生成文件的日期，共8位XXXXXX: 6位的批次号 P: 代扣回盘文件文件内容格式规范：文件内容包括文件头和文件体。文件头与文件体由回车换行符分割。文件头: 文件的第一行，包含：商户号，批次号，总笔数，总金额，各项用“|”分割。如下表所示：“12345000000001|000001|100|90000”No数据项内容说明1商户号12345000000001ChinaPay分配给商户的唯一标识 定长15位2批次号000001商户上传文件的批次号 定长 6位3总笔数1000

30、当前文件中，交易明细总数， 变长5位，同发盘文件 4总金额90000交易总金额，以分为单位，最长长度15位文件体: 文件体存放的是具体的交易数据，一行代表一笔交易记录。在每一行交易记录中，交易所需的各项都用“|”隔开，具体说明见下表。每一行交易明细中的各项尽可能不要有空格存在。No项目描述格式长度是否必须备注1商户日期数字定长，8位必须标志该笔交易在商户端发生的日期，可与批量文件实际上传日期不同2订单号数字定长，16位必须交易记录流水号，同商户日期一起唯一标识文件中的一笔交易3开户行代号数字定长，4位必须如中国工商银行代号：01024卡折标志数字定长，1位必须表示随后记录为卡号或存折号(0:卡

31、,1:折)5卡号/折号字符变长，25位必须银行卡号或者存折号码6持卡人姓名字符变长，40位（二十个汉字）必须7身份类型字符定长，2位必须证件类型，定义如下：身份证01 , 军官证02 ,护照03 , 户口簿04 , 回乡证05 , 其他068证件号码字符变长，25位必须9金额数字变长，12位必须（整型）整数，以分为单位 10用途字符变长，25位必须扣款用途11私有域字符变长，60位必须商户专用12响应码字符定长， 4位必须13响应描述字符变长，60位14额外域字符变长，30位例子如808080032288119_20110421_211001_P.txt4.3 商户交易请求数据签名和验签说明4

32、.3.1. 核心文件清单名 称放置的路径用 途netpayclinet.jar根据项目工程的需要放置对应路径下用于提供数字签名的方法调用MerPrk.key可以放置到任意路径下，但是需要调用方法指定文件位置和名称商户签名私钥PgPubk.key可以放置到任意路径下，但是需要调用方法指定文件位置和名称ChinaPay签名公钥4.3.2. 方法说明创建公/私钥对象buildKey方法说明：public boolean buildKey (String MerId, int KeyUsage, String KeyFile) 作用： 用于创建私/公钥的对象，用于签名或者验证签名。参数说明：Strin

33、g MerId 商户号，长度为15个字节的数字串，由ChinaPay分配。 int KeyUsage 使用私/公钥的方式，固定为 0 。String KeyFile 私/公钥的文件路径（包含文件名称）。例如："d:MerPrk.key”返回值：true 表示找到正确的私/公钥文件,并且可以调用签名方法签名或者签名验证方法验证签名；false表示创建私/公钥对象失败，不可以使用签名方法和签名验证方法。注：该方法在类chinapay.PrivateKey中。对一段字符串的签名函数Sign方法说明：public String Sign (String SignMsg)作用：对传入的参数字符

34、串进行数字签名。参数说明：String SignMsg 用于要签名的字符串返回值： String CheckValue256即NetPayClient根据上述输入参数生成的商户数字签名，长度为256字节的 字符串。注：该方法在类chinapay.SecureLink中。对一段字符串的签名验证函数verifyAuthToken方法说明：public boolean verifyAuthToken (String PlainData, String CheckValue) 作用：验证目标字符串的数字签名是否正确。参数说明：String PlainData 用于数字签名的字符串。 String Ch

35、eckValue 校验值，要验证的字符串的数字签名，长度为256字节的字符串。 返回值：true 表示验证通过成功；否则表示失败。注：该方法在类chinapay.SecureLink中。4.3.3. 使用示例代码（以下代码未经测试，仅供参考）签名示例代码/初始化key文件 chinapay.PrivateKey key=new chinapay.PrivateKey(); boolean flag = key.buildKey(merId,0,"D:eclipseMerPrk.key"); if (flag = false) System.out.println("

36、;build key error!"); return; /将要签名的数据传给signMsgString signMsg = merId + orFileName + fileName;System.out.println("要签名的数据:"+ msg);/对签名的明文进行MD5摘要，并将摘要内容转换为Asc码 String msg = Hex2Asc(getMD5(signMsg.getBytes("UTF-8").length, getMD5(signMsg.getBytes("UTF-8"); System.out.p

37、rintln("要签名的数据进行md5摘要后为:"+ msg);/签名 SecureLink s = new SecureLink(key);chkValue = s.Sign(msg);System.out.println("签名内容:"+ chkValue);验证签名示例代码/初始化key文件 chinapay.PrivateKey key=new chinapay.PrivateKey(); boolean flag = key.buildKey(merId,0,"D:eclipsePgPubk.key"); if (flag

38、= false) System.out.println("build key error!"); return; /截取验签明文传给signMsgString result = html.toString();int dex = result.lastIndexOf("=");String signMsg = result.substring(0, dex + 1);System.out.println("验签明文：" + "" + signMsg + "");/截取验签密文chkValue值S

39、tring chkValue = result.substring(dex + 1);System.out.println("验签密文:"+ chkValue);/对验签的明文进行MD5摘要，并将摘要内容转换为Asc码 String msg = Hex2Asc(getMD5(signMsg.getBytes("UTF-8").length, getMD5(signMsg.getBytes("UTF-8"); System.out.println("要验签的数据进行md5摘要后为:"+ msg);/验签 SecureLink s = new SecureLink(key);boolean res = false;res = s2.verifyAuthToken(msg, chkValue); if(res = false)/签名验证错误处理System.out.println("验签失败！False!");elseSystem.out.println("验签成功！True!&q