财付通批量银行代付接口开发手册

Version: 3.0

Public date: 2011-5-22

All copyright reserved by Tenpay.com

目 录

第1章 文档描述 5

1.1 文档说明 5

1.2 版本 5

1.3 预期读者和阅读建议 5

第2章 业务描述 5

2.1 接口作用 5

2.2 银行代付接口限制 5

第3章 前期准备 6

3.1.1 业务准备 6

3.1.2 技术准备 6

第4章 接口说明 6

4.1 结构说明 6

4.1.1 接入URL 6

4.1.2 接口原理 7

4.2 批量银行代付接口 7

4.2.1 功能描述： 7

4.2.2 需要开通功能： 7

4.2.3 接入URL 7

4.2.4 输入参数 8

4.2.5 返回参数 9

4.2.6 接口特别说明 9

4.3 批量银行代付查询接口 10

4.3.1 功能描述： 10

4.3.2 需要开通功能： 10

4.3.3 输入参数 10

4.3.4 返回参数 11

4.3.5 返回参数说明 13

4.4 退票查询接口 13

4.4.1 功能描述： 13

4.4.2 需要开通功能： 13

4.4.3 请求参数 13

4.4.4 返回参数 14

第5章 附录和枚举 16

5.1 付款到账时间 16

5.2 银行编码 17

5.3 开户地区编码 19

5.3.1 北京 19

5.3.2 上海 19

5.3.3 天津 19

5.3.4 重庆 19

5.3.5 河北 19

5.3.6 山西 20

5.3.7 内蒙古 20

5.3.8 辽宁 21

5.3.9 吉林 21

5.3.10 黑龙江 22

5.3.11 江苏 22

5.3.12 浙江 23

5.3.13 安徽 23

5.3.14 福建 24

5.3.15 江西 24

5.3.16 山东 25

5.3.17 河南 25

5.3.18 湖北 26

5.3.19 湖南 26

5.3.20 广东 27

5.3.21 广西 27

5.3.22 海南 28

5.3.23 四川 28

5.3.24 贵州 29

5.3.25 云南 29

5.3.26 西藏 30

5.3.27 陕西 30

5.3.28 甘肃 31

5.3.29 宁夏 31

5.3.30 青海 32

5.3.31 新疆 32

5.4 安全性说明 33

5.5 代付查询 33

5.6 代付明细查询 34

5.7 电子回单 35

5.8 对账单下载 35

5.9 财付通对应付款银行说明 36

5.10 财付通付款手机短信通知格式 36

5.11 错误码 37

文档描述

1.1 文档说明

本操作手册用来指导财付通商户实现与财付通银行代付接口的顺利对接。请相关技术人员详细阅读本手册。

文中红色的内容表示要重点注意的内容。

1.2 版本

1.3 预期读者和阅读建议

商户开发人员、技术支持人员、财务人员

业务描述

1.4 接口作用

财付通批量银行代付是对商户账户内的可支配金额，批量转账到用户的银行卡中的解决方案。

1.5 银行代付接口限制

1、银行代付接口不是一个实时到账接口，接口调用成功只代表信息已经提交到财付通，财付通汇总后再提交到银行，银行到账也有一定延迟，一般1~2个工作日后可以到账（各银行的到账时间不同）。

2、代付接口调用成功后，有可能由于填写用户银行账户信息不完整或其他原因，导致付款失败。商户必须通过查询接口确认用户是否到账。

3、代付接口中需要按照财付通要求，填写开户地区、开户城市、支行名称等银行信息。

前期准备

业务准备

由于银行代付操作中，会验证商户发起请求的IP、权限等，所以在此之前，需要先申请操作权限以及配置信任IP列表。

申请此业务功能，请联系财付通商务人员

技术准备

因为该接口基于https的安全通信机制，因此商户在选择开发语言时需要能支持HTTPS协议通讯。

接口说明

接口协议源数据为XML格式字符串，源数据经过编码和加密之后生成接口参数。商户端需要完成加密，传输，证书验证等功能的开发。

1.6 结构说明

接入URL

https://mch.tenpay.com/cgi-bin/mchbatchtransfer.cgi

支持POST方式。如果付款数据太多，使用GET方式会有问题，建议统一使用POST方式。

接口原理

财付通接口接收两个参数，content和abstract，商户访问的形式是https://mch.tenpay.com/cgi-bin/mchbatchtransfer.cgi?content=***&abstract=***。

这两个参数值的具体生成规则是：

1.按照4.2、4.3节的规则生成XML字符串A；

2.对A进行BASE64编码生成B；

3.对B进行MD5生成C（小写）；

4.C后面加上商户的key再进行一次MD5，生成D（小写）；

计算公式如下：

content的值为:B=base64_encode(XML字符串);

abstract的值为:D=md5(md5(content)+key)，加号表示连接，不要参与md5.

注解：XML字符串是请求参数的原始值按照XML格式拼接起来，参数顺序按照ASCII码排序，去掉空格和回车换行。

1.7 批量银行代付接口

功能描述：

批量银行代付功能,此接口只是记录商户传入的批量银行代付的信息，实际的银行代付操作由财付通系统的后台批处理程序完成，所以此接口只会返回上传记录的处理结果，银行代付的处理结果由批量银行代付查询接口返回。

需要开通功能：

需要开通"批量银行代付"的权限。

接入URL

https://mch.tenpay.com/cgi-bin/mchbatchtransfer.cgi或者异步接口

https://mch.tenpay.com/cgi-bin/i_batch_draw_async.cgi

特别说明：i_batch_draw_async.cgi接口一个批次支持最多999笔记录；mchbatchtransfer.cgi接口一个批次支持最多5-10笔记录，后续后台可能会调整，具体数值可以通过进行实际测试获取。两个接口请求参数和请求方式完全一致，商户可根据自身业务情况选择使用。

输入参数

xml version="1.0" encoding="GB2312" ?>

<root>

<op_code>1013op_code>

<op_name>batch_drawop_name>

<op_user>操作员op_user>

<op_passwd>操作员密码op_passwd>

<op_time>操作时间（yyyyMMddhhmmssSSS）op_time>

<sp_id>商户机构IDsp_id>

<package_id>包序列ID（YYYYMMDDXXX，长度不超过30),批次号不能重复package_id>

<total_num>总笔数total_num>

<total_amt>总金额(以分为单位)total_amt>

<client_ip>客户端IP地址client_ip>

<record_set>

<record>

<serial>单笔序列号（同一个批次内的明细序号要保证唯一，不能超过32个字符）serial>

<rec_bankacc>收款方银行帐号rec_bankacc>

<bank_type>银行类型（每个银行对应的4位数字编码）bank_type>

<rec_name>收款方真实姓名（个人名称大于等于4个字节，公司名称大于等于9个字节）rec_name>

<pay_amt>付款金额(以分为单位)pay_amt>

<acc_type>账户类型(1为个人账户,2为公司账户)acc_type>

<area>开户地区(1～2位数字编码，不支持汉字，可以填写为0。见财付通提供的开户地区编码)area>

<city>开户城市(1～4位数字编码，不支持汉字，可以填写为0。见财付通提供的开户城市编码)city>

<subbank_name>支行名称（汉字，可以填写为全角空格）subbank_name>

<desc>付款说明desc>

<recv_mobile>付款接收通知手机号recv_mobile>

record>

...(每一笔明细对应一个record结点)

record_set>

root>

说明：total_num标识该批次包含的所有明细的总笔数，必须等于结点的个数。total_amt表示该批次包含的所有明细的金额的总和，必须等于每个结点中付款金额(<pay_amt>的值)之和。

返回参数

xml version="1.0" encoding="GB2312" ?>

<root>

GB2312

<op_code>1013op_code>

<op_name>batch_drawop_name>

<op_user>提交人IDop_user>

<op_time>操作时间（yyyyMMddhhmmssSSS）op_time>

<package_id>包序列ID（YYYYMMDDXXX）package_id>

(本接口result恒为空)/result>

<retcode>返回码：0或00-提交成功，其他见5.11的说明retcode>

<retmsg>错误内容描述retmsg>

root>

接口特别说明

1、 字符编码必须是GBK编码；

2、 批次号需保证全局唯一，不是当天唯一，格式没有特殊要求，长度限制为30个字符，同一个批次在服务器端只会被处理一次；

3、 同一个批次内的统计数据必须和明细数据匹配，如总金额必须等于明细记录金额之和，总记录数必须与明细记录数相同；

4、 同一个批次内的明细序号要保证唯一，不能超过32个字符，批次号和明细序号唯一确定一条记录；

5、 鉴于XML的可扩展性，返回参数可能会有新增，且顺序并不一定完全遵循此文档规范；

6、 除5.11章节描述的错误码之外的错误，财付通均不能保证已经操作成功或者失败，需要通过财付通网站或者查询接口进行二次确认.

1.8 批量银行代付查询接口

功能描述：

批量银行代付查询接口，查询指定批次的批量银行代付结果。

需要开通功能：

需要开通"批量银行代付"的权限。

输入参数

xml version="1.0" encoding="GB2312" ?>

<root>

<op_code>1014op_code>

<op_name>batch_draw_queryop_name>

<service_version>1.1service_version>

<op_user>提交人IDop_user>

<op_passwd>操作员密码op_passwd>

<op_time>操作时间（yyyyMMddhhmmssSSS）op_time>

<sp_id>商户机构IDsp_id>

<package_id>包序列ID（YYYYMMDDXXX，长度不超过30）package_id>

<client_ip>客户端IP地址client_ip>

root>

说明：package_id是调用批量银行代付接口时指定的包序列ID。

返回参数

xml version="1.0" encoding="GB2312" ?>

<root>

<op_code>1014op_code>

<op_name>batch_draw_queryop_name>

<op_user>提交人IDop_user>

<op_time>操作时间（yyyyMMddhhmmssSSS）op_time>

<package_id>包序列ID（YYYYMMDDXXX）package_id>

<retcode>返回码：0或00-查询成功retcode>

<retmsg>错误内容描述retmsg>

<result> --本结构只有在返回码为0或00时有意义-->

<trade_state>批次状态（1初始状态，2待审核，3可付款，4付款失败，5处理中，6受理完成,7已取消）trade_state>

<total_count >总笔数total_count>

<total_fee>总金额</total_fee>

<succ_count>成功笔数succ_count>

<succ_fee>成功金额succ_fee>

<fail_count>失败笔数fail_count>

<fail_fee>失败金额fail_fee>

<origin_set>

<origin_total>初始状态条数origin_total>

<origin_rec>

单笔序列号

收款方银行帐号

银行类型

收款方真实姓名

付款金额(以分为单位)

账户类型>

开户地区

开户城市

支行名称

付款说明

origin_rec>

<success_set>

<suc_total>成功条数suc_total>

<suc_rec>

单笔序列号

收款方银行帐号

银行类型

收款方真实姓名

付款金额(以分为单位)

账户类型>

开户地区

开户城市

支行名称

付款说明

suc_rec>

success_set>

<tobank_set>

<tobank_total>已提交银行条数tobank_total>

<tobank_rec>

单笔序列号

收款方银行帐号

银行类型

收款方真实姓名

付款金额(以分为单位)

账户类型>

开户地区

开户城市

支行名称

付款说明

tobank_rec>

tobank_set>

<fail_set>

<fail_total>失败条数fail_total>

<fail_rec>

单笔序列号

收款方银行帐号

银行类型

收款方真实姓名

付款金额(以分为单位)

账户类型>

开户地区

开户城市

支行名称

失败原因

fail_rec>

fail_set>

<handling_set>

<handling_total>处理中条数handling_total>

<handling_rec>

单笔序列号

收款方银行帐号

银行类型

收款方真实姓名

付款金额(以分为单位)

账户类型>

开户地区

开户城市

支行名称

付款说明

handling_rec>

handling_set>

<return_ticket_set>

<ret_ticket_total>退票条数ret_ticket_total>

<ret_ticket_rec>

　　 单笔序列号

　　 收款方银行帐号

　　 银行类型

　　 收款方真实姓名

　　 付款金额(以分为单位)

　　 账户类型>

　　 开户地区

　　 开户城市

　　 支行名称

　　 付款说明

ret_ticket_rec>

return_ticket_set>

result>

root>

返回参数说明

当查询成功时,result结点下是每笔明细的信息，财付通系统批处理程序会间歇性的处理每条记录，直到每条记录处理成功或者失败，但是处理的过程中会有中间状态，每笔明细的状态有6种，以下是每种状态的描述：

1、初始状态（origin_set里面的记录）： 还没有经过处理，最终会转化为成功或失败。

2、成功状态（success_set里面的记录)：付款已经成功，资金已转入银行账户。

3、已提交银行状态（tobank_set里面的记录):付款需求已提交，等待财务处理，资金还未转入银行账户，最终会转化为成功或失败。

4、失败状态（fail_set里面的记录)：付款失败。

5、处理中状态(handling_set里面的记录)： 正在处理中，最终会转化为成功或失败。

6、已退票状态（return_ticket_set里面的记录）：银行退票记录。版本号service_version为1.1时返回该节点。

1.9 退票查询接口

功能描述：

退票查询接口，查询代付退票信息。

T+1日只能查询到T日以及T日之前的退票记录，不能查询到T+1日产生的退票记录。

需要开通功能：

需要开通"批量银行代付"的权限。

请求参数

请求URL：http://mch.tenpay.com/cgi-bin/agent_pay_refund.cgi

带证书双向HTTPS通讯，通过GET或POST请求

返回参数

cancel_rec说明：

返回码：0-查询成功

错误内容描述

商户号partner>

<cancel_count>退票笔数cancel_count>

<sign>签名sign>

<cancel_set>

<cancel_rec>

提现单号

包序列ID（YYYYMMDDXXX，长度不超过30)

单笔序列号

付款金额(以分为单位)

银行编码

代付发起时间

退票产生时间

退票原因

</cancel_rec>

<cancel_rec>

</cancel_rec>

<cancel_set>

附录和枚举

1.10 付款到账时间

1.11 银行编码

银行类型填写银行编号，请按以下格式填写：

每笔付款内容要填写的“省市开户行”的要求，银行之间存在差异，现阶段要求如下：

(注：Y表示银行有校验，N表示银行无校验。由于目前接口要求省市开户行字段必填，对值为N的银行，对应的字段需要填写一个固定值)

Y:代表必填项目；N：代表不必填项

其中广发对私的单笔付款额度为5万元人民币，光大银行对私单笔付款额度为100万，其他银行单笔付款额度都可到达500万元人民币。每个批次不能超过999条付款记录，批次总金额不能超过2000万元。

1.12 开户地区编码

北京

上海

天津

重庆

河北

山西

内蒙古

辽宁

吉林

黑龙江

江苏

浙江

安徽

福建

江西

山东

河南

湖北

湖南

广东

广西

海南

四川

贵州

云南

西藏

陕西

甘肃

宁夏

青海

新疆

1.13 安全性说明

为了保证系统的安全，财付通进行了一些安全限制，下边是一些注意事项：

1、 请妥善保管好个人数字证书和密码，谨防泄漏。

2、 请妥善保管好操作员帐号和密码，谨防泄漏。

3、 服务器配置文件中保存了个人密码，该机器和目录要进行权限控制。

4、 定期通过财付通网站修改商户密码（注意同时更新配置文件）。

5、 客户机要进行安全访问控制，以免虚假客户端通过服务器发送转账请求。

6、 其他：财付通后台会对访问的用户权限、IP地址、访问频率等进行限制。

1.14 代付查询

1、在此界面点击“下载”，可将对应的批次记录导出到xls文件。

2、点击查看按钮之后，可以看到该批次的具体信息如下：

3、点击明细按钮后，可以看到该批次的所有明细记录状态信息如下,点击“导出链接”，可将界面查出的记录导出到xls格式的文件，点击回单查询，可以看到批量明细中的每笔付款的电子回单信息。

1.15 代付明细查询

在代付明细查询中，可以根据不同查询条件查询每条明细记录的信息，在该界面对于代付成功的记录，可点击回单查询链接，查看电子回单。

1.16 电子回单

在代付查询的明细信息和代付明细查询功能里面，每条付款成功状态的记录后面的操作栏，会有一个“回单查询”链接，点击进去后，可以看到该笔付款成功记录的电子回单信息，示例如下：

当非商户号登录，收款用户直接使用链接http://mch.tenpay.com/rct/在线查询验证可以看到以上回单信息，唯一区别就是不显示财付通付款专用章。

1.17 对账单下载

下图是对账单下载页面，对账单下载日期必须是付款成功并银行回导后的日期：

如果下载某一天的对账单，使用指定日期后的下载按钮即可；如果需要多个日期的对账单合成一个文件，使用指定日期范围后的打包下载按钮,最长支持31天的对账单合并。下载后的对账单文件格式为excel文件。

注：为避免付款信息被随意下载，该功能如果操作员需要使用，需要管理员进行授权，如下图所示权限：

1.18 财付通对应付款银行说明

1、财付通支持直付到：中国工商银行、招商银行、中国建设银行、中国农业银行、上海浦东发展银行、中信实业银行、广东发展银行、中国交通银行、深圳发展银行、中国民生银行、华夏银行。

2、财付通还支持付款到:中国光大银行、中国银行、平安银行、兴业银行、北京银行、广州银联、农村商业银行、农村信用合作社等。

3、在批量上传文件中，如果不是直付银行，可以在“银行类型”项输入银行名称（比如中国光大银行），也可以输入“其他银行”。需要注意的是在输入非直付银行时一定要完整输入开户省、开户城市、开户支行名称。

4、如果付款到农行对私的存折，请在存折号码前两位代码后加“-”（英文输入状态下的横杠），比如44485300460083684，必须是这么输入：44-485300460083684。

对公存折不需要加“-”。

1.19 财付通付款手机短信通知格式

*****公司于****年**月**日向***尾数为****的银行账户存入了***金额***。使用回单号*****，验证码*****，登录http：//mch.tenpay.com/rct/查询。【财付通】

根据短信具体内容长度，会截成两条发送。

1.20 错误码

1.21 退票说明

退票：代付申请通过财付通提交给银行处理后，银行返回结果是处理成功，财付通通知商户代付成功；但间隔一段时间后，银行再次通知财付通代付失败并返还代付款项给财付通，财付通再将该笔失败款返还至商户的现金账户中。
退票原因：部分银行（如中国邮政储蓄银行）的付款申请需先通过人民银行的支付系统，再由接收行（如中国邮政储蓄银行）入账处理，此时如存在账号、户名或支行信息错误或其他不能入账的原因，接收行会将款项再退回到原汇出行（财付通）。所以，一笔付款，人民银行的支付系统会先返回成功状态，但是若接收行入账失败，会再次通知付款失败。

财付通批量银行代付接口开发手册