寂寂无言IPPS产品对商户端接口标准
单位中国银行
撰写人IPPS开发组
版本
修订说明
序号修改人日期版本号修改说明
1.梁栋2010-6-26 Ver 0.1 完成初稿
2.梁栋2010-11-8 Ver 0.2 修改查询类接口的返回报文
3.乔大伟2010-11-17 Ver 0.3 将本文档定义为产品级文档，补充所有对商户端接口。
4.梁栋2010-12-7 Ver 0.4 修改理财直付和协议支付批量部分字段项
5.乔大伟2011-03-16 Ver 0.5沪苏吴批次针对人行二号令对本文档进行如下修改：
2.2.4 修改银行返回订单支付结果(页面通知)
2.2.5 修改银行返回订单支付结果(主动通知)
2.2.7 新增商户发送查询订单请求(支持卡户信息判
断)
5.2.10 修改商户发送订单支付请求
6.2.1.4新增商户发送B2B订单查询请求(支持卡户信息
判断)
6.乔大伟2011-05-23 Ver 1.1 [公共]
以湘鄂桂批次实现为基线，建立基础版本1.1
7.乔大伟2011-06-13 Ver 1.2.1 [粤深]
4.2.3 修改银行反馈认证结果(主动通知)增加
notifyType
8.乔大伟2011-06-17 Ver 1.2.2 [公共]
整理文档内容，重新归纳安全机制，整理联机部分接口。
9.乔大伟2011-06-21 Ver 1.2.3 [粤深]
5.2.4 修改商户发送修改协议请求增加agreeUrl。10.李红梅2011-06-21 Ver 1.2.4 [公共]
6.2.2 修改根据B2B相关文档补充数据说明项
11.李红梅2011-07-25 Ver 1.2.5 [公共]
2.2.12 删除交易流水文件生成
12.乔大伟2011-07-25 Ver 1.3.1 [粤深后批次] 铁道部紧急需求变更
修改商户发送网上银行支付订单
13.李新2011-10-24 Ver 1.4.1 [P201]
修改协议支付签约返回结果增加签约渠道
修改协议支付签约、改约、解约，查询协议、订单支
付，查询订单接口中返回数据项卡号返回规则修改
14.李新2012-03-14 Ver 1.5.1 [P204]
新增商户对接上传下载文件接口规约
15.乔大伟2012-04-19 Ver 1.6.1 [P205]
16.李红梅2012-07-09 Ver 1.7.1 [P207]
新增商户发送网上银行分期支付订单
17.梁栋2012-07-25 Ver 1.7.2 [P207]
新增分行特色业务接口
18.乔大伟
陈发建2012-08-31 Ver 1.8.1 [P301]
文档结构进行重大调整；
梁晓晓协议支付增加对商户属性管理的支持；
19.梁栋2012-9-18 Ver 1.8.2 [P301]
B2B订单支付(监管商户、非监管商户)增加超时时间数据
项
20.李红梅2012-11-01 Ver 1.8.3 [P301]
修改B2B订单查询接口的返回报文和示例
21.李红梅2012-11-21 Ver 1.8.4 [P301]
增加P301错误码
22.张鹤2013-9-5 Ver 1.9.1 [P401]
B2C协议支付增加访问者IP和访问者Refer信息
23.乔大伟2013-9-17 Ver 1.10.1 [P402]
商户发送B2B订单支付请求(直付商户)增加二级商户信息
商户发送B2B订单支付请求(保付商户)增加二级商户信息
24.乔大伟
张鹤2013-11-5 Ver 1.11.1 [P401]
新增对B2C体彩商户接口规约
注：版本号规则a.b.c 其中a表示大版本更新，b表示批次更新，c表示批次内修改流水。
1.2.x 表示这些修改都是在粤深批次进行的。
IPPS
第1章概述
1.1文档说明
本文描述了中国银行IPPS相关服务通讯协议、报文格式、安全机制等内容。作为商户端系统技术人员开发的参考文档。
1.2编写目的
为使商户端系统开发人员了解IPPS服务的相关通讯接口细节。
1.3通讯协议
目前中行系统支持以下三种方式与商户系统通讯：
通过客户浏览器间接通讯：
a. 商户引导客户浏览器，将信息提交到网银系统。商户发送身份认证指令以及支付指
令接口时采用该方式通讯。表单数据中需包含商户对身份认证信息和订单信息的签名。
b. 网银引导客户浏览器将信息提交到商户系统。网银反馈身份认证和支付结果接口采
用该通讯方式。表单数据中包含网银系统的签名信息。
商户操作员通过浏览器操作网银：
商户操作员登录网银操作网银功能，用来下载业务对账文件与清算对账文件。（网银
系统提供的其他商户操作员功能如状态查询等由于不涉及系统之间的接口规范，因此
不再描述）
直接通讯：
商户系统与网银系统之间直接建立通讯链路，该通讯采用HTTPS协议，由商户系统主动发起通讯。支付状态查询接口、身份认证结果查询接口等业务采用此通讯方式。1.4安全机制
商户与支付网关之间的通讯采用HTTPS协议，SSL握手时验证支付网关服务器证书，加密算法要求128位以上。服务器证书采用Verisign签发的中国银行网上银行服务器证书。SSL协议保证传输通道的安全，包括通讯数据加密、服务器身份认证。客户端的身份认证依靠银行验证商户的数据签名实现。
IPPS 产品总体设计(商户端接口)
网银团队支付小组 第 5 页 共 172页 中国银行CA 中心为商户签发文件签名证书，用于对商户发送的请求指令(如支付指令、支付状态查询指令)进行签名，中国银行CA 中心为网上支付系统签发交易签名证书，用于对银行反馈处理结果(页面通知、主动通知)进行签名。中国银行还要给商户提供中行CA 中心二级根证书，用于商户验证银行反馈处理结果的签名信息。
1.5 签名与验签
签名原文串采用UTF-8(无BOM)格式。
商户进行数字签名：
数字签名采用pkcs7格式，经过BASE64编码传送。签名中不包括被签名的明文，包括签名公钥证书。明文由交易要素字符串组成，需要注意金额数据格式要求整数部分不补0，小数部分补足两位，日期格式为14位24小时格式：“YYYYMMDDHHMISS ”。 交易
数字签名明文格式 示例交易 示例明文由管道符“|”分割，如：
商户订单号|订单时间|订单币种|订单金额|商户号
orderNo|orderTime|curCode|orderAmount|merchantNo
签名证书存在文件形式的证书库中，证书库可以是pfx 格式或jks 格式，由中行提供。调用中行提供的PKCS7Tool.jar 中的PKCS7Tool 类可以在java 中实现签名。
签名代码示例如下：
// String keyStorePath: 证书库路径
// String keyStorePassword: 证书库口令
// String keyPassword: 签名私钥口令，一般与证书库口令相同
PKCS7Tool tool = PKCS7Tool.getSigner (keyStorePath, keyStorePassword, keyPassword);
//签名，返回signature ：base64格式的签名结果
// byte[] data: 明文字符串
String signature = tool.sign(data);
商户验证银行数字签名：
数字签名采用pkcs7格式，经过BASE64编码传送。签名中不包括被签名的明文，包括签名公钥证书。
IPPS 产品总体设计(商户端接口)
网银团队支付小组 第 6 页 共 172页 交易
数字签名明文格式 示例交易 示例明文由管道符“|”分割，如：
商户号|商户订单号|银行订单流水号|银行卡类别|支付时间|订单状态|支付金额
merchantNo|orderNo|orderSeq|cardTyp|payTime|orderStatus|payAmount
调用中行提供的PKCS7Tool.jar 中的PKCS7Tool 类可以在java 中实现验证签名。验证签名需要提供银行发送的签名结果、签名明文、由中行提供的cer 格式的信任公钥证书文件。
签名代码示例如下：
// String rootCertificatePath: 根证书路径
PKCS7Tool tool = PKCS7Tool.getVerifier (rootCertificatePath);
//验签名，如果失败抛出异常
// String signature ：签名
// byte[] data ：明文数据
// String dn ：银行签名证书DN ，如果为空则不验证DN
tool.verify(signature, data, dn);
商户验证银行数字签名异常后的处理：
在实际业务处理环境中，如果银行签名环节出现异常，提供商户的签名项为空，则会导致商户验证银行签名失败或异常。出现这种情况为保证商户尽快处理交易，建议商户主动向银行网关发起订单查询获得订单支付状态。
1.6 数据类型定义
报文规范中数据类型的定义说明：
9表示数字型数据。 X 表示字符型数据。
IPPS 产品总体设计(商户端接口)
网银团队支付小组 第 7 页 共 172页
1.7 联机接口示例
1.7.1 商户发送请求示例
商户系统请按照相关接口定义采用POST 方式发送请求至我行支付网关，内容请使用UTF-8编码格式。下面以 B2C 标准商户订单支付 为例说明商户系统上送数据形式 (本节以下内容仅
作为示例使用)。 接口名称： RecvOrder.do 数据项说明：
序号 名称
字段
最大长度
说明
1. 商户号 merchantNo
X(20) ………. 2. 支付类型 payType X(10) ………. 3. 商户订单号 orderNo X(19) ………. 4. 订单币种 curCode
X(3) ………. 5. 订单金额 orderAmount X(13) ………. 6. 订单时间 orderTime 9(14) ………. 7. 订单说明
orderNote X(200) ………. 8. 商户接收通知URL orderUrl
X(100) ………. 9. 超时时间 orderTimeoutDate 9(14) ………. 10. 商户签名数据
signData
X(4000)
……….
接口示例：
IPPS 产品总体设计(商户端接口)
网银团队支付小组 第 8 页 共 172页
1.7.2 商户接收银行通知示例
我行提供的接口名称中如果提及页面通知或主动通知，银行系统均按照相关接口定义向商户系统发送POST 通知，内容使用UTF-8编码格式。以B2C 标准商户订单支付 为例，说明商户系统接收到银行系统反馈数据形式 (本节以下内容仅作为示例使用)
数据项说明： 序号 名称
字段
最大长度
说明 1. 商户号 merchantNo X(20) ………. 2. 商户订单号 orderNo X(19) ………. 3. 银行订单流水号 orderSeq 9(20) ………. 4. 银行卡类别 cardTyp X(2) ………. 5. 支付时间 payTime
9(14) ………. 6. 订单状态 orderStatus X(2) ………. 7. 支付金额
payAmount X(13) ………. 8. 客户支付IP 地址
orderIp X(40) ………. 9. 客户浏览器Refer 信息 orderRefer X(200) ………. 10. 银行交易流水号 bankTranSeq X(22) ………. 11. 返回操作类型 returnActFlag X(1) ………. 12. 电话号码 phoneNum X(50) ………. 13. 中行签名数据
signData
X(4000)
……….
接口示例：
----------header info-------------- user-agent=Java/1.5.0
host=221.123.123.123:8080
accept=text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 connection=keep-alive
content-type=application/x-www-form-urlencoded content-length=1969
----------para info-------------- merchantNo=104012345678901 orderNo=TEST0001 orderSeq=12345678 cardTyp=12
payTime=20091225182140 orderStatus=1 payAmount=0.01
orderIp=201.12.12.12
orderRefer=http%3A%2F%2Flocalhost%2FB2C bankTranSeq=2009122533011575000001 returnActFlag=1 phoneNum=
signData=MIIEZgYJKoZu3ukpfzDOJ8onjJl+gUxoP1FcWqQqlhzo
IPPS 产品总体设计(商户端接口)
网银团队支付小组 第 9 页 共 172页
1.7.3 银行直连接收交易结果示例
针对商户与银行直连类交易（如联机退货、订单查询等），我行均按照相关接口定义采用XML 格式同步返回交易结果，内容使用UTF-8编码格式。
以 B2C 订单查询 为例，说明银行系统同步反馈数据形式 (本节以下内容仅作为示例使
用)。
序号
报文要素
备注
1.
Message root
BusinessHeader 业务头报文块
3.
--MessageId 报文标识号
……….
4.
--HandleStatus 处理状态
