1、1代收付系统接口代收付系统接口文档属性文档名称： 代收付系统接口项目名称： 代收付系统当前版本号： 2.5创建者： 技术开发部 创建日期： 2009-04-15复核者： 复核日期：审批者： 审批日期：版本历史：版本号 修改内容 撰写者 发布日期1.0 创建 2009-04-151.1 查询报文增加返回CUST_USERID、 REMARK去掉用户密码加密修改了例子多余的2009-05-041.2 增加验证账户交易 2009-05-251.3 查询交易增加备注 2009-06-021.4 增加查询交易反馈码(无法查询该交易 ) 2009-06-031.5 增加了部分业务代码 2009-08-24
2、1.6 代收 代付 验证交易版本升级为 04 2009-09-021.7 增加了代收和代付业务代码，详见蓝体字。 郭飙 2009-09-041.8 请求报文明细增加域 RECKON_ACC, RESERVED1, RESERVED22009-10-211.9 增加查询当日或历史查询交易 邓广和 2009-10-212.0 增加报文压缩协议 2009-11-052.1 增加协议同步接口 2010-07-2722.2 修正部分与实际不一样的定义 2011-07-132.3 增加业务代码，修改测试地址为二代地址增加 FTP 交易请求，FTP 处理结果查询请求、差错查询接口，通知类报文邵静 2011-
3、12-212.4 增加交易与响应码详细说明，增加账户类接口， 邵静 2012-06-072.5 增加银行账户接口，增加下载清算文件接口，增加 05 版报文，扩展数据域，反馈代码说明更新邵静 2013-01-06版权声明：此文档的版权归广州银联网络支付有限公司所有，作为本系统的最终用户，可以拥有该份文档的使用权，但未征得广州银联网络支付有限公司的书面批准，不得向第三方借阅、出让、出版该文档。3目录1. 文档介绍 .71.1 读者对象 .71.2 术语与缩写解释 .72. 接口通讯 .82.1 通讯方式 .82.2 信息体说明 .82.2.1 编码要求 82.2.2 Xml 报文说明 82.3 安
4、全 .82.4 交易流程 .92.4.1 发起交易 92.4.2 查询交易结果 102.4.3 交易和响应码应用详细说明 103. 交易类报文 .133.1 批量代收请求（04 版） 133.1.1 请求报文说明 133.1.2 响应报文说明 153.1.3 例子 163.2 批量代收请求（05 版） 213.2.1 请求报文说明 213.2.2 响应报文说明 243.3 批量代付请求（04 版） 253.3.1 请求报文说明 253.3.2 响应报文说明 273.3.3 例子 283.4 批量代付请求（05 版） 333.4.1 请求报文说明 333.4.2 响应报文说明 363.5 验证账
5、户请求（04 版） 373.5.1 请求报文说明 373.5.2 响应报文说明 393.5.3 例子 403.6 准实时代付请求（05 版） 453.6.1 请求报文说明 453.6.2 响应报文说明 4843.7 实时代收请求（04 版） 493.7.1 请求报文说明 493.7.2 响应报文说明 513.7.3 例子 523.8 实时代收请求（05 版） 563.8.1 请求报文说明 563.8.2 响应报文说明 593.9 实时代付请求（04 版） 603.9.1 请求报文说明 603.9.2 响应报文说明 623.9.3 例子 633.10 实时代付请求（05 版） 663.10.1
6、请求报文说明 663.10.2 响应报文说明 703.11 交易结果查询请求（03 版） 713.11.1 请求报文说明 713.11.2 返回报文说明 713.11.3 例子 723.12 交易结果查询请求（05 版） 753.12.1 请求报文说明 753.12.2 返回报文说明 763.13 银行账户余额查询 .773.13.1 请求报文说明 773.13.2 返回报文说明 793.13.3 例子 803.14 FTP 交易请求（03 版） 803.14.1 请求报文说明 803.14.2 返回报文说明 813.15 FTP 交易请求（05 版） 813.15.1 请求报文说明 813.
7、15.2 返回报文说明 823.16 FTP 处理结果查询请求（03 版） 833.16.1 请求报文说明 833.16.2 返回报文说明 843.17 FTP 处理结果查询请求（05 版） 843.17.1 请求报文说明 843.17.2 返回报文说明 853.18 当日或历史查询请求（03 版报文） 863.18.1 请求报文说明 863.18.2 返回报文说明 8653.18.3 例子 873.19 当日或历史查询请求（05 版报文） 913.19.1 请求报文说明 913.19.2 返回报文说明 923.20 当日或历史查询请求（压缩文本格式） .943.20.1 请求报文说明 943
8、.20.2 返回报文说明 953.20.3 结果文本格式说明 963.21 差错或异常退汇查询请求 .973.21.1 请求报文说明 973.21.2 返回报文说明 983.22 清算文件下载 .993.22.1 请求报文说明 993.22.2 响应报文说明 993.22.3 清算文件格式说明 994. 通知类 .1014.1 FTP 文件处理结果通知（03 版） 1014.1.1 通知报文说明 1014.2 FTP 文件处理结果通知（05 版） 1014.2.1 通知报文说明 1014.2.2 返回报文说明 1024.3 划款通知 .1024.3.1 通知报文说明 1024.3.2 返回报文
9、说明 1035. 协议同步和账号签约 .1045.1 账号签约请求 .1045.1.1 请求报文说明 1045.1.2 返回报文说明 1055.1.3 例子 1065.2 协议同步结果查询请求 .1095.2.1 请求报文说明 1095.2.2 返回报文说明 1105.2.3 例子 1116. 账户类 .1146.1 账户余额查询 .1146.1.1 请求报文说明 1146.1.2 返回报文说明 1146.1.3 例子 1166.2 账户明细查询 11666.2.1 请求报文说明 1166.2.2 返回报文说明 1176.3 账户内部转账请求 .1196.3.1 请求报文说明 1196.3.2
10、 响应报文说明 1206.3.3 例子 1216.4 转账结果查询 .1216.4.1 请求报文说明 1216.4.2 响应报文说明 1226.5 账户充值请求 .1226.5.1 请求报文说明 1226.5.2 响应报文说明 1246.6 充值结果查询 .1246.6.1 请求报文说明 1246.6.2 响应报文说明 1256.7 账户提现请求 .1256.7.1 请求报文说明 1266.7.2 响应报文说明 1266.8 提现结果查询 .1276.8.1 请求报文说明 1276.8.2 响应报文说明 1287. 附录 .1297.1 代付业务代码 .1297.2 代收业务代码 .1307.
11、3 银行代码 .1317.4 反馈代码表 .1347.5 交易代码 .1387.6 中国邮政区号表 .1397.7 SOCKET 方式 .1397.8 测试 .1447.9 R&Q14471. 文档介绍1.1 读者对象1.2 术语与缩写解释缩写、术语 解 释银联网络 广州银联网络支付有限公司缩写代收付系统 广州银联网络支付有限公司代收付系统代收 代收业务是指收费单位得到持卡人授权后，再授权银联网络从持卡人的银行卡帐户或存折持有人的存折帐户中扣除代收费款项的业务形式。如代收电费、水费、通讯费等。代付 代付业务，是指付费单位在提供付款目标相关银行账户信息及对应款项后，通过银联网络的跨行代付系统，实
12、现向个人账户批量划款。请求商户 指发起交易的商户，具体为请求报文头中用户名对应的商户82. 接口通讯2.1 通讯方式代收付系统提供接口使用 HTTPS 作为通讯方式，报文格式为 XML。可选择用 zip 格式压缩报文再传输，方式：用标准 ZIP 格式压缩报文后再对压缩后的内容进行 Base64 编码。如使用 SOCKET 方式，请参见附录 7 说明，需要进行配置方可进行测试。2.2 信息体说明2.2.1 编码要求本系统报文接口数据使用的是 GBK 编码。2.2.2 Xml 报文说明对于无信息内容的标签，该标签可不出现，但若此标签在某些情况下是必填项时，不出现会报错，请根据错误原因检查。请注意报
13、文版本号的填写。2.3 安全通讯使用 HTTPS 进行通讯，交易内容使用数字证书进行签名（签名原文为把完整交易报文的“”开始位置到“”这些字符替换为“”后的字符串） 。默认的签名算法为 SHA1withRSA，我司提供 JAVA 和.NET 的签名包，请参照开发包进行开发和调试。签名请使用私钥（.pfx） ，验签请使用公钥（.cer） ，相关证书在商户投产前会有专人发送给接口人。92.4 交易流程商户 收付易平台发起请求指令 （ h t t p p o s t ）处理返回已接收 ( h t t p 反馈 )定时轮询查询结果发起查询 （ h t t p p o s t ）返回结果 ( h t t
14、 p 反馈 )处理返回信息交易处理2.4.1 发起交易使用报文 200001，200002，200003 发起批量代收、批量代付、准实时代付（验证交易），使用 http post 方式提交到代收付服务器，代收付服务器返回是否接受该请求的响应（反馈码是“0000”为正确接受，其它为失败，失败原因看反馈原因） 。使用报文 200004，200005 发起实时代收、实时代付交易，使用 http post 方式提交到代收付服务器，代收付服务器返回是否处理完成该请求的响应，正常情况下会返回交易结果，批次反馈码是 0000 为处理完成，明细响应码为具体的交易结果。在银行不确定或者没有收到银行响应的情况下，
15、实时代收交易会有两种返回方式：一种是批次返回0000，明细返回 3059（渠道返回结果不明确，系统直接置失败，这种情况下如果有代收长款，则由我司与银行对账后直接退回持卡人，一般在 T+1 进行退款） ；另一种是批次返回 2000，表示交易还在处理中，在与银行对账后置最终结果（成功或失败） ，由商户再发起查询，直到查询到批次反馈码是 0000 为止。这两种方式由商户根据自身情况选择其中一种模式。实时代付在不确定银行结果的情况下，则是直接返回 2000，系统不会直接置失败。102.4.2 查询交易结果使用报文 200001 发起查询交易结果，使用 http post 方式提交到代收付服务器，代收付
16、服务器返回要查询的交易的结果（反馈码“0000”是正确处理完毕，结果是最终结果；反馈码“0001”是代收付系统对交易数据处理失败；反馈码“0002”为该批交易撤销；反馈码“1002”代表代收付系统没有查询到该交易，代表该批交易服务器没有收到，可以用同一流水重发；“2*”的代表代收付系统正在处理交易） 。报文体返回的是该批交易的明细结果（明细反馈码见附录 7.4 的查询交易明细） 。2.4.3 交易和响应码应用详细说明说明：对应报文头响应码 RET_CODE 以下为 RET_CODE_INFO对应报文体响应码 RET_CODE 以下为 RET_CODE_DETAIL一 . 对于 100001（批
17、量代收） ，100002（批量代付） ，100003（准实时代付）这两个交易1 当 RET_CODE_INFO = 0000 时，表示系统接收成功，可以在一段时间后发起200001（交易结果查询请求）交易，以获得交易最终状态即成功或失败。2 当 RET_CODE_INFO 为 1000，1001 则系统提交失败，需检查报文是否有误后再提交；3 当 RET_CODE_INFO 为 1，2 之外的情况时，则交易处于中间处理状态，发起200001（交易结果查询请求）交易，以获得交易最终状态即成功或失败。二 . 对于 200001 交易（查询 100001，100002，100004，100005 提
18、交的交易）注意：查询交易请不要频繁提交，会影响系统响应速度，如果一个批次中交易数量较多，请将第一次查询间隔放到 7 分钟，超过一万笔请将第一次查询间隔放在 10 分钟以上。我系统还提供主动推送报文结果功能，需贵方提供一个服务，我方将在一个批次处理完成后，将 200001 的结果格式报文推送到贵方。1 当 RET_CODE_INFO = 0000 时，如果 RET_CODE_DETAIL=0000 ，则交易成功，如果 RET_CODE_DETAIL0000 则交易失败；三、对于 100004（实时代收） ，100005（实时代付）这两个交易1 当 RET_CODE_INFO = 0000 时，如
19、果 RET_CODE_DETAIL=0000 ，则交易成功，11如果 RET_CODE_DETAIL25616SIGNED_MSG签名信息 C 否 对本报文的所有信息进行签名（除本域外 也不含）SN 记录序号 C(1,25) 可RET_CODE返回码 C(4) 可 附录 4 反馈代码表-BODY/RET_DETAILS/ RET_DETAILERR_MSG错误文本 C(1,256) 可数字签名原文为没有 SIGNED_MSG签名信息项的 xml 全文。3.1.3 例子请求1000010425testtest2009041611084101签名信息106000010531100000012009
20、0416120000220001105001760138270140042110021张三广东广州建行01CNY保险理赔00021050060138270140042110022李四广东广州建行01CNY保险理赔18请求信息签名原文1000010420testtest200904161108410110600001053110000001200904161200002200011050060138270140042110021张三广东广州建行01CNY19保险理赔00021050060138270140042110022李四广东广州建行01CNY保险理赔响应100001042200904161
21、10841010000签名信息200001000000020000响应信息签名原文100001042200904161108410100000001000000020000213.2 批量代收请求（05 版）3.2.1 请求报文说明接口 字段 ID 字段名称 类型 取值 可空 备注TRX_CODE 交易代码 C(1, 20) 100001 否VERSION 版本 C(2) 05 否 版本 05 进行了字段扩展，变更内容在字段说明中会标出DATA_TYPE 数据格式 N(1) 2：xml 格式 可LEVEL 处理级别 N(1) 0-90 实时处理默认 5可 目前暂时只提供批量处理USER_NAM
22、E 用户名 C(1,20) 否USER_PASS 用户密码 否REQ_SN 交易流水号 C(30) 否 不重复流水(对代收付系统需要唯一)INFOSIGNED_MSG 签名信息 C 否 对本报文的所有信息进行签名（除本域外 也不含）BUSINESS_CODE 业务代码 C(6) 见附录 4.2 非空MERCHANT_ID 商户代码 C(15) 银联网络商户ID非空EXPECT_SEND_TIME预约发送时间C (14) YYYYMMDDHHMMSS 可空 版本 05 新增，原提交时间不再由商户提交，提交时间为系统接收到交易的时间，系统会在预约时间发送到银行，不填表示即收即发TOTAL_ITEM
23、 总记录数 N (1,4) 非空BODY/TRANS_SUMTOTAL_SUM 总金额 N (1,12) 整数，单位分 非空22SN 记录序号 C(1,25) 同一个请求内必须唯一。建议从0001 开始递增非空E_USER_CODE银联网络用户编号C(1,20) 银联网络客户编号可空BANK_CODE 银行代码 C(8) 3-8 位的银行代码，见附录 4.3非空 版本 05 开始银行代码扩展长度到最长 8 位，原 3位代码不变ACCOUNT_TYPE账号类型 C(2) 00 银行卡，01存折。可空 版本 05 开始在不填时，查询交易会返回系统根据卡 BIN 判断后的代码ACCOUNT_NO账号
24、 N(1,32) 银行卡或存折号码非空 版本 05 开始对于农行的存折，如果商户要求系统进行处理，则系统将去掉省份代码后的账号发到银行进行交易，查询交易返回处理后的账号。ACCOUNT_NAME账号名 C(1,60) 银行卡或存折上的所有人姓名。非空PROVINCE 开户行所在省C (1,20) 不带“省”或“自治区” ，如 广东，广西，内蒙古等。建议根据后附的中国邮政区号表内的“省洲名称”列的内容填写。可空 版本 05 开始对于农行、中行，如果不填省份，系统默认根据商户所在地填写的省份，查询交易返回默认值BODY/TRANS_DETAILS/TRANS_DETAILCITY 开户行所在市C
25、(1,20) 不带“市” ，如 广州，南宁等。 如果是直辖市，则填区，如北京（市）朝阳（区）。建议根据后附的中国邮政区号表内的“地区名称”列的内容填写。可空23BANK_NAME 开户行名称 C (1,60) 开户行详细名称，也叫网点，如 中国建设银行广州东山广场分理处。可空ACCOUNT_PROP账号属性 C (1) 0 私人，1 公司。不填时，默认为私人 0。可空 版本 05 开始，查询交易会返回默认值AMOUNT 金额 N(1,12) 整数，单位分 非空CURRENCY 货币类型 C (3) 人民币：CNY, 港元：HKD，美元：USD 。不填时，默认为人民币。可空 版本 05 开始，查
26、询交易会返回默认值PROTOCOL 协议号 C (1,60) 可空PROTOCOL_USERID协议用户编号C (1,30) 可空ID_TYPE 开户证件类型C (1) 0：身份证,1: 户口簿，2：护照,3.军官证,4.士兵证，5. 港澳居民来往内地通行证,6. 台湾同胞来往内地通行证,7. 临时身份证,8. 外国人居留证,9. 警官证 , X.其他证件可空 版本 05 开始，查询交易会返回默认值ID 证件号 C (1,22) 可空TEL 手机号/小灵通C (1,13) 小灵通带区号，不带括号，减号可空RECKON_ACCOUNT清算账号 C(1,30) 资金清算账号 可空 商户有需要把一天
27、的交易清算到不同账户时填写，查询交易原样返回CUST_USERID自定义用户号C (1,20) 商户自定义的用户号， 用户号要唯一可空 查询交易原样返回REMARK 备注 C (1,50) 供商户填入参考信息可空 查询交易原样返回RESERVE1 保留域 1 C(1,50) 备用字段 1 可空 查询交易原样返回24RESERVE2 保留域 2 C(1,50) 备用字段 2 可空 查询交易原样返回RESERVE3 保留域 3 C(1,50) 备用字段 3 可空 版本 05 新增，查询交易原样返回RESERVE4 保留域 4 C(1,50) 备用字段 4 可空 版本 05 新增，查询交易原样返回E
28、LE_BANKNO电子联行号 C（12） 可空 版本 05 新增，如果为空，有需要的渠道会由系统自动匹配，查询交易时返回匹配值ABS 摘要 C(1,50) 可空 版本 05 新增PS 附言 C(1,50) 可空 版本 05 新增USE 用途 C(1,50) 可空 版本 05 新增CRE_VAL_DATE信用卡有效期C（4） YYMM 可空 版本 05 新增，信用卡用CRE_CVN2 CVN2 码 C(1,50) 可空 信用卡用ACC_PASS 账号密码 C(1,20) 可空 版本 05 新增,请填空，在特殊交易时使用，目前未有银行支持，未来使用时会加密上送数字签名原文为没有 SIGNED_MS
29、G签名信息项的 xml 全文。3.2.2 响应报文说明接口 字段 ID 字段名称 类型 取值 可空 备注TRX_CODE 交易代码 C(1, 20) 100001 否VERSION 版本 C(2) 05 可 与请求的版本一致DATA_TYPE数据格式 N(1) 2：xml 格式 可REQ_SN 交易流水号 C(16) 否 同请求流水RET_CODE 返回代码 C(4) 否 附录 4 反馈代码表-批量代收代付交易INFOERR_MSG 错误信息 C(1,256) 可 实际返回长度可能25625SIGNED_MSG签名信息 C 否 对本报文的所有信息进行签名（除本域外 也不含）SN 记录序号 C(
30、1,25) 可RET_CODE返回码 C(4) 可 附录 4 反馈代码表-BODY/RET_DETAILS/ RET_DETAILERR_MSG错误文本 C(1,256) 可数字签名原文为没有 SIGNED_MSG签名信息项的 xml 全文。3.3 批量代付请求（04 版）3.3.1 请求报文说明接口 字段 ID 字段名称 类型 取值 可空 备注TRX_CODE 交易代码 C(1, 20) 100002 否VERSION 版本 C(2) 04 可 版本 04 修正了返回报文少了 xml头的问题，为空默认为 04 版DATA_TYPE 数据格式 N(1) 2：xml 格式 可LEVEL 处理级别
31、 N(1) 0-90 实时处理默认 5可 目前暂时只提供批量处理USER_NAME 用户名 C(1,20) 否USER_PASS 用户密码 否REQ_SN 交易流水号 C(30) 否 不重复流水(对代收付系统需要唯一)INFOSIGNED_MSG 签名信息 C 否 对本报文的所有信息进行签名（除本域外 也不含）BODY BUSINESS_CODE 业务代码 C(6) 见附录 4.2 非空26MERCHANT_ID 商户代码 C(15) 银联网络商户ID非空SUBMIT_TIME 提交时间 C (14) YYYYMMDDHHMMSS 可空TOTAL_ITEM 总记录数 N (1,4) 非空/TR
32、ANS_SUMTOTAL_SUM 总金额 N (1,12) 整数，单位分 非空SN 记录序号 C(1,25) 同一个请求内必须唯一。建议从0001 开始递增非空E_USER_CODE银联网络用户编号C(1,20) 银联网络客户编号可空BANK_CODE 银行代码 C(3) 3 位的银行代码，见附录 4.3非空ACCOUNT_TYPE账号类型 C(2) 00 银行卡，01存折。不填默认为银行卡 00。可空ACCOUNT_NO账号 N(1,32) 银行卡或存折号码非空ACCOUNT_NAME账号名 C(1,60) 银行卡或存折上的所有人姓名。非空PROVINCE 开户行所在省C (1,20) 不带
33、“省”或“自治区” ，如 广东，广西，内蒙古等。建议根据后附的中国邮政区号表内的“省洲名称”列的内容填写。可空CITY 开户行所在市C (1,20) 不带“市” ，如 广州，南宁等。 如果是直辖市，则填区，如北京（市）朝阳（区）。建议根据后附的中国邮政区号表内的“地区名称”列的内容填写。可空BODY/TRANS_DETAILS/TRANS_DETAILBANK_NAME 开户行名称 C (1,60) 开户行详细名称，也叫网点，如 中国建设银行广州东山广场分理处。可空27ACCOUNT_PROP账号属性 C (1) 0 私人，1 公司。不填时，默认为私人 0。可空AMOUNT 金额 N(1,12
34、) 整数，单位分 非空CURRENCY 货币类型 C (3) 人民币：CNY, 港元：HKD，美元：USD 。不填时，默认为人民币。可空PROTOCOL 协议号 C (1,60) 可空PROTOCOL_USERID协议用户编号C (1,30) 可空ID_TYPE 开户证件类型C (1) 0：身份证,1: 户口簿，2：护照,3.军官证,4.士兵证，5. 港澳居民来往内地通行证,6. 台湾同胞来往内地通行证,7. 临时身份证,8. 外国人居留证,9. 警官证 , X.其他证件可空ID 证件号 C (1,22) 可空TEL 手机号/小灵通C (1,13) 小灵通带区号，不带括号，减号可空RECKON
35、_ACCOUNT清算账号 C(1,30) 资金清算账号 可空 商户有需要把一天的交易清算到不同账户时填写CUST_USERID自定义用户号C (1,20) 商户自定义的用户号， 用户号要唯一可空REMARK 备注 C (1,50) 供商户填入参考信息可空RESERVE1 保留域 1 C(1,50) 备用字段 1 可空RESERVE2 保留域 2 C(1,50) 备用字段 2 可空数字签名原文为没有 SIGNED_MSG签名信息项的 xml 全文。3.3.2 响应报文说明接口 字段 ID 字段名称 类型 取值 可空 备注TRX_CODE 交易代码 C(1, 20) 100002 否VERSION
36、 版本 C(2) 04 可INFODATA_TYPE数据格式 N(1) 2：xml 格式 可28REQ_SN 交易流水号 C(16) 否RET_CODE 返回代码 C(4) 否 附录 4 反馈代码表-批量代收代付交易ERR_MSG 错误信息 C(1,256) 可 实际返回长度可能256SIGNED_MSG签名信息 C 否 对本报文的所有信息进行签名（除本域外 也不含）SN 记录序号 C(1,25) 可RET_CODE返回码 C(4) 可BODY/RET_DETAILS/ RET_DETAILERR_MSG错误文本 C(1,256) 可数字签名原文为没有 SIGNED_MSG签名信息项的 xml
37、 全文。3.3.3 例子请求1000020425operator12009041611084101签名信息0060000105311000000120090416120000222900011050060138270140042110021张三广东广州建行01CNY保险理赔00021050060138270140042110022李四广东广州建行01CNY30保险理赔请求签名信息原文1000020420operator1200904161108410100600001053110000001200904161200002200011050060138270140042110021张三广东广州建行01CNY
