吉林手机支付系统交易网关接口规范（第三方接入部分）@20080730

本文档及其所含信息为机密材料 由北京神州数码思特奇信息技术股份有限公司拥有，未经面授权， 不得将材料泄露给第三方 COPYRIGHT © 2008保留所有权利 吉林移动手机支付系统 交易网关接口规范 （第三方接入部分） 版本 1.3 北京神州数码思特奇信息技术股份有限公司 二〇〇八年七月 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 2 页 共 33 页 文 档 信 息 文档名称： 吉林移动手机支付系统交易网关接口规范 电子文档： 吉林移动手机支付系统交易网关接口规范.doc/Microsoft WORD 2000 版本号： 1.1 密级： 保密 文档状态： □ 草 稿 ■ 正式发布 □ 正在修改 编写人： 毛蔚 日期： 2008-02-21 校对人： 日期： 审核人： 日期： 批准人： 日期： 更 改 记 录 更改 序号 更改原因 更改 页码 更改前 版本号 更改后 版本号 更改人 生效日期 备 注 1 文档建立 1.0 2 修改了通信节 点定义(6.1)和 交易代码定义 （6.4） 1.1 张清锁 2008-3-19 3 积分消费、积 分撤销、积分 冲正的响应包 增加积分字段 1.2 张清锁 2008-6-25 4 调整话费对账 第三方上传的 文件名 1.3 张清锁 2008-7-30 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 3 页 共 33 页 目 录 1. 概述 .............................................................................................................................................................. 5 1.1. 协议说明 ............................................................................................................................................ 5 1.2. 适用范围 ............................................................................................................................................ 5 1.3. 参考资料 ............................................................................................................................................ 5 1.4. 业务术语 ............................................................................................................................................ 5 2. 系统结构...................................................................................................................................................... 6 3. 通信...................................................................................................................................................... 8 3.1. 通信方式 ............................................................................................................................................ 8 3.2. 通信节点编码............................................................................................................................ 8 3.3. 序列号的定义 .................................................................................................................................... 9 3.4. 通信的安全性 .................................................................................................................................... 9 3.5. 通信描述 ..........................................................................................................................................10 3.5.1. 通信初始化 ...............................................................................................................................10 3.5.2. 通信过程 ...................................................................................................................................10 3.5.3. 通信结束 ...................................................................................................................................11 3.5.4. 故障处理 ...................................................................................................................................12 3.5.4.1. 网络故障 ............................................................................................................................. 12 3.5.4.2. 接受到非法命令和应答 ...................................................................................................... 12 3.5.4.3. 序列号重复 ......................................................................................................................... 12 3.5.5. 通信消息 ...................................................................................................................................12 4. 消息定义....................................................................................................................................................14 4.1. 数据类型 ..........................................................................................................................................14 4.2. 消息头格式 ......................................................................................................................................14 4.3. 消息体格式 ......................................................................................................................................14 4.3.1. Bind 操作 ..................................................................................................................................14 4.3.1.1. Bind 命令的语法 ................................................................................................................. 15 4.3.1.2. Bind_Resp 应答的语法........................................................................................................ 15 4.3.2. Unbind 操作 ..............................................................................................................................15 4.3.2.1. Unbind 命令的语法 ............................................................................................................. 15 4.3.2.2. Unbind_Resp 应答的语法.................................................................................................... 15 4.3.3. Trans 操作.................................................................................................................................16 4.3.3.1. 积分查询(Query) ................................................................................................................. 16 4.3.3.2. 积分消费(Consuse).............................................................................................................. 16 4.3.3.3. 积分撤消(Cancel) ................................................................................................................ 17 4.3.3.4. 积分冲正(Corre) .................................................................................................................. 18 4.3.3.5. 话费查询(Query) ................................................................................................................. 19 4.3.3.6. 话费消费(Consume) ............................................................................................................ 20 4.3.3.7. 话费撤消(Cancel) ................................................................................................................ 20 4.3.3.8. 话费冲正(Corre) .................................................................................................................. 21 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 4 页 共 33 页 4.3.4. KeepAlive 操作 .........................................................................................................................22 5. 离线对帐....................................................................................................................................................23 5.1. 积分对帐 ..........................................................................................................................................23 5.2. 话费对帐 ..........................................................................................................................................26 6. 常量定义....................................................................................................................................................29 6.1. 通信节点定义 ..................................................................................................................................29 6.2. 消息 ID 定义....................................................................................................................................29 6.3. 返回代码定义 ..................................................................................................................................29 6.4. 交易代码定义 ..................................................................................................................................30 6.5. 业务标志定义 ..................................................................................................................................31 7. 附录 ............................................................................................................................................................32 7.1. 交易数据报文示例..........................................................................................................................32 7.1.1. 消费交易请求报文 ..................................................................................................................32 7.1.1.1. 报文头部分 ......................................................................................................................... 32 7.1.1.2. 报文体部分 ......................................................................................................................... 32 7.1.2. 消费交易应答报文 ..................................................................................................................33 7.1.2.1. 报文头部分 ......................................................................................................................... 33 7.1.2.2. 报文体部分 ......................................................................................................................... 33 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 5 页 共 33 页 1. 概述 1.1. 协议说明 本协议是手机支付系统交易网关与 POS 中心或第三方系统间的通信接口协 议。通过本协议，POS 中心或者第三方业务系统可以进行手机用户的积分/话费 查询，积分/话费消费，积分/话费消费冲正处理。 1.2. 适用范围 本协议适用于手机支付系统与第三方业务系统（包括 POS 中心、自助终端 系统）间的交易过程。 如果不作特殊说明的，协议文档中所有提及 POS 中心的地方，同样适用于 其他的第三方接入系统。 1.3. 参考资料 [1]《银行磁条卡销售点终端规范》 [2]《中国银联直联 POS 终端规范》 1.4. 业务术语 本协议用到以下术语： 1、交易协议 交易网关向第三方接入系统提供的交易协议，协议详细描述了消息交互过程， 消息格式，以及基本交易代码定义等。 2、销售点终端 Point Of Sale（POS） 能够接受磁条卡信息，具有通讯功能，并接受柜员的指令而完成金融交易信 息和有关信息交换的设备。 3、POS 中心 POS Center 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 6 页 共 33 页 接受处理或转发 POS 的交易请求信息，并向 POS 回送交易结果信息的机构； 4、主密钥 Primary Key 第三方系统申请接入交易网关时，由交易网关的管理员分配的用于交易过程 中加密重要信息（比如：登陆账户密码，交易密钥等）的密钥。 5、交易密钥 Transaction Key 用于交易过程中加密数字摘要信息（MD5）和重要交易信息的密钥。 6、MD5 （Message-Digest Algorithm 5） 在 90 年代初由 MIT的计算机科学和 RSA Data Security Inc 发明，经 MD2、MD3 和 MD4 发展而来。Message-Digest 泛指字节串(Message)的 Hash 变 换，就是把一个任意长度的字节串变换成一定长的大整数。 MD5 将任意长度的“字节串”变换成一个 128bit 的大整数，并且它是一个不 可逆的字符串变换算法，换句话说就是，即使你看到源程序和算法描述，也 无法将一个 MD5 的值变换回原始的字符串，从数学原理上说，是因为原始的 字符串有无穷多个，这有点象不存在反的数学函数。 MD5 的典型应用是对一段 Message(字节串)产生 fingerprint(指纹)，以防止 被“篡改”。MD5 还广泛用于加密和解密技术上，在很多操作系统中，用户 的密码是以 MD5 值（或类似的其它算法）的方式保存的， 用户 Login 的时候， 系统是把用户输入的密码计算成 MD5 值，然后再去和系统中保存的 MD5值进 行比较，而系统并不“知道”用户的密码是什么。 2. 系统结构 交易网关是手机支付系统的重要组件，它负责和其他外部系统的连接，根据 不同交易请求，完成对应的业务处理。 图 2-1 说明了手机支付系统交易网关的位置，以及交易协议的使用位置。 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 7 页 共 33 页 数据库 交易网关 POS中心 POS机 WebServer POS机 POS机 POS机 „„ 交易协议 ISO8583或其他协议 自动售货系统 交易协议 图 2-1 交易网关位置 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 8 页 共 33 页 3. 通信流程 3.1. 通信方式 交易协议通过 TCP 承载，交易网关在通信过程中一直作为通讯的服务端， POS 中心为客户端。当 POS 中心需要进行交易处理时，需作为通信的客户端主 动向交易网关发起连接请求，通过交易网关的鉴权认证后，才能发起交易报文并 接受交易网关返回的应答。 连接建立以后，客户端可以连续发送多条命令。命令发送完并接收到所有应 答后，客户端应该主动断开连接。但是，命令及其应答之间的时间间隔最大不能 超过 30 秒(默认，可配置)（如果命令应答时间超过最大等待时间，则要求客户 端重发该条命令），且待应答的命令不得超过 32 条（可随业务发展情况，根据 线路的质量和服务器的处理能力配置）。而且，如果服务器端检测出一条连接长 时间空闲(默认 60 秒，可配置)，可以主动断开该连接。如果需要，客户端可以 同时向一个服务器端建立多个连接，但是最多不能建立超过 15 个连接。 交易网关的服务监听端口号约定为 8899。 3.2. 通信节点编码规则 对于交易网关来说，所有的第三方通信节点(POS 中心，第三方系统、内部 系统等)都需要有一个唯一的数字编号，不同的第三方系统的编号不能相同，编 号由交易网关的系统管理人员负责分配。 编号规则如下： POS 中心的编号规则 ：1XX 第三方系统的编号规则 ：2XX 内部系统的编号规则 ：9XX 【说明】XX表示 2 位序号（由交易网关统一分配此编码） 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 9 页 共 33 页 3.3. 序列号的定义 交易网关和第三方系统之间传输的每一条命令都有一个序列号，序列号由命 令源节点（即：请求消息的发起方）产生并唯一标记一条命令；也就是说，交易 网关和第三方系统中任何两个命令的序列号都不相同。需要注意的是，一条命令 在发送过程中请求和应答，使用相同的序列号。比如，POS 中心向交易网关发送 一条请求命令携带的序号，将与交易网关回复 POS 中心的应答报中的序号相同。 序列号分成三部分，每部分为一个 32 位整数。第一部分表示命令源节点的 编号（参见通讯节点定义）；第二部分表示命令产生的日期和时间(交易网关中 的任何命令的保存时间都不超过一年，超过一年的消息将作备份处理)，格式为 十进制的 mmddhhmmss，比如 11月 20日 20 时 32 分 25秒产生的命令，其第二部 分为十进制 1120203225；第三部分由 0开始，循环进位，直到进位满了之后再 清零，重新开始计数。 接收方在返回应答时，应答的序列号必须和相对应的命令的序列号相同。 有了序列号，协议的双方应用程序可以灵活实现交易过程。POS 中心可以串 行的发送请求等待应答方式，也可以批量发送请求然后批量处理应答（当然此时 是需要根据序号进行请求和应答的匹配）。如果 POS 中心只采用串行的发送请 求等待应答方式，那么序列号的机制可以不使用，但是在协议报中保留该字段， 以确保协议的扩展性。 3.4. 通信的安全性 为了确保通信过程中的交易信息安全，交易信息采用对称加密（DES 加密） 方式进行。POS 中心接入交易网关时，交易网关将分配给它一个主密钥（要求 POS 中心能支持主密钥的定期手工动态更换）。 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 10 页 共 33 页 对于 POS 中心每次接入交易网关，交易网关将动态产生此次交易的交易密 钥，交易密钥的传输过程使用主密钥加密处理。交易密钥用于此次批量交易过程 中，对交易信息数字摘要（MD5）等的加密处理；此交易密钥在通信链路断开后 失效，POS 中心再次请求连接时，交易网关将生成新的交易密钥。 3.5. 通信描述 3.5.1. 通信初始化 POS 中心有交易要向交易网关发送时，首先通过 Bind 命令向交易网关发起 连接。交易网关根据连接系统的 IP 地址、以及 Bind 命令之中的登录名和密码， 对请求连接系统的合法性进行验证，然后返回一条 Bind_Resp 应答给 POS 中心。 如果验证通过，则和交易网关的通信开始，否则交易网关将自动中断连接。 3.5.2. 通信过程 POS 中心发送的任何一条命令都带有一个序列号，序列号由命令源产生（即： 请求的发起方）。客户端与服务器端通信开始以后，客户端可以向服务器端发送 相应的命令，服务器端对收到的命令返回应答。短信发送过程可以描述如下： 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 11 页 共 33 页 交易网关 POS中心/ 第三方接入系统 Bind Bind_Resp Trans(1) Trans_Reasp(1) Trans(2) Trans(3) Trans_Reasp(2) Trans_Reasp(3) Unbind Unbind_Resp „„ Unbind Unbind_Resp 或者 消息交互过程 3.5.3. 通信结束 当 POS 中心认为和交易网关的通信已结束，则应该向交易网关发送 Unbind 命令，交易网关随后将返回 Unbind_Resp 应答，然后双方断开连接。 当交易网关检查到链路在设定的时间内没有接受到消息时，也可以主动断开 和 POS 中心的通信链路，断开操作通过向 POS 中心主动发送 Unbind 命令，POS 中心接受到 Unbind 请求后返回 Unbind_Resp 应答，然后双方断开连接。 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 12 页 共 33 页 3.5.4. 故障处理 3.5.4.1. 网络故障 POS 中心与交易网关通信过程中如果检测到双方连接中断(如网络断线)， POS 中心应该断开连接，然后尝试重新向交易网关建立新的连接；交易网关应该 按照接收到 Unbind 的情况进行处理，断开和 POS 中心的连接。 3.5.4.2. 接受到非法命令和应答 如果交易网关接收到的命令语法错误，比如命令不完整、命令无法识别等， 则断开和 POS 中心的连接；POS 中心应该向交易网关建立新连接继续发送命令。 如果 POS 中心接收到的应答语法错误，比如命令不完整、命令无法识别等， 则主动断开和交易网关的连接；交易网关也应该断开和 POS 中心的连接。 如果命令语法正确，但交易网关不处理该命令，则给 POS 中心返回相应应 答，并在应答中指定错误原因。 如果应答语法正确，但 POS 中心不处理该应答，则丢弃。 3.5.4.3. 序列号重复 如果命令的序列号和以前接收到的命令的序列号相同，且命令内容也相同， 则接收方丢弃该命令，并保留相应的日志备核查；如果序列号相同，但是命令内 容并不相同，则命令接收方在应答中返回错误码。 3.5.5. 通信消息 消息 消息描述 Bind 建立连接的请求 Bind_Resp 连接的应答 Unbind 断开连接的请求 Unbind_Resp 断开连接的应答 Trans 交易请求 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 13 页 共 33 页 Trans_Resp 交易应答 KeepAlive 链路检测请求 KeepAlive_Resp 链路检测应答 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 14 页 共 33 页 4. 消息定义 4.1. 数据类型 消息中利用到如下数据类型： 类型 说明 Integer 无符号整数 Text 定长字符串，左对齐存储，空余位置补’\0’ 消息中的所有 Integer 类型的字段均采用网络字节顺序。所有消息中的序列 号字段均占 12 个字节，分为 3个 4字节整数；通信传输时每个整数都使用网络 字节顺序，但整数的次序并不改变。也就是说，通信传输的时候，序列号字段应 该按照三个连续的 4字节整数来处理。 4.2. 消息头格式 报文头为定长的二进制格式，报文头各字段的含义如下所示： 字段 长度（字节） 类型 说明 Message Length 4 Integer 消息的总长度(字节) Command ID 4 Integer 命令 ID Sequence Number 12 Integer 序列号 4.3. 消息体格式 交易协议的报文体使用二进制流的方式传输，根据协议报的不同，报文体为 变长的。在通信过程中，报文体的实际长度可以由报文头的长度来算出。 4.3.1. Bind 操作 Bind 操作由 Bind 命令和 Bind_Resp 应答组成。POS 中心首先发送 Bind 命令， 交易网关收到 Bind 命令后，对命令发送方进行验证，然后返回 Bind_Resp 应答。 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 15 页 共 33 页 4.3.1.1. Bind 命令的语法 字段名 字段含义 类型 长度 说明 loginName 登陆账户 Text 10 交易网关分配的登陆账户 loginPasswd 帐户对应密码 Text 30 交易网关分配的帐户密码，使 用主密钥进行了DES 加密， 此时此处为加密后的密文 4.3.1.2. Bind_Resp 应答的语法 字段名 字段含义 类型 长度 说明 result Bind 请求结果 unsigned char 1 0－成功 1－失败（注意 此处是数值型的 0 和 1，不 是 ASCII 的’0’和’1’） transKey 交易密钥 Text 39 交易网关产生的交易密 钥，此交易密钥将由主密 钥使用DES 加密，此处是 密文字符串 4.3.2. Unbind 操作 Unbind 操作由 Unbind 命令和 Unbind_Resp 应答组成。通信连接建立以后， POS 中心如果要停止通信，需要发送 Unbind 命令；交易网关收到 Unbind 命令后， 向 POS 中心送 Unbind_Resp 相应，然后双方断开连接。 4.3.2.1. Unbind 命令的语法 Unbind 命令没有消息体。 4.3.2.2. Unbind_Resp 应答的语法 Unbind_Resp 命令没有消息体。 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 16 页 共 33 页 4.3.3. Trans 操作 Trans 操作是实际的消息交易报，按照交易类型的不同，报文体部分的内容 也不一样。下面将就积分查询、扣减、冲正和粘贴卡与手机绑定关系查询等交易 的报文体分别加以说明。 4.3.3.1. 积分查询(Query) 4.3.3.1.1. Trans 命令的语法 字段名 字段含义 类型 长度 说明 transType 交易代码 Text 2 参见交易代码定义 transData 交易日期 Text 8 YYYYMMDD transTime 交易时间 Text 6 HHMMSS（24 小时制） transNo 交易流水号 Text 19 交易流水号 relatingNo 手机号 Text 19 手机号 reserve 备用字段 Text 2 用于协议报按 32 位对齐 4.3.3.1.2. Trans_Resp 应答的语法 字段名 字段含义 类型 长度 说明 transType 交易代码 Text 2 参见交易代码定义 result 交易结果 Text 4 参见返回代码定义 point 积分值 Text 10 当前积分值 4.3.3.2. 积分消费(Consuse) POS 中心必须保证上送的交易流水号的唯一性。 4.3.3.2.1. Trans 命令的语法 字段名 字段含义 类型 长度 说明 transType 交易代码 Text 2 参见交易代码定义 transData 交易日期 Text 8 YYYYMMDD transTime 交易时间 Text 6 HHMMSS（24 小时制） 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 17 页 共 33 页 transNo 交易流水号 Text 19 交易流水号 relatingNo 手机号 Text 19 手机号 point 积分值 Text 10 需要扣减的话费值 md5_DES 数字摘要 Text 98 先由交易报文中 19位长的 “transNo”＋19位长的 “relatingNo”＋10位长“point” 依次拼接组成的字符串进行 MD5 数字摘要得到字符串 S1， 然后对 S1使用交易密钥进行 DES 加密后得到字符串 S2，此 处存放的就是 S2 busiFlag 业务标志 Text 2 参见业务标志定义 channelName 渠道名称 Text 20 渠道名称 shopName 商户名称 Text 40 商户名称 busiName 业务名称 Text 40 交易说明 4.3.3.2.2. Trans_Resp 应答的语法 字段名 字段含义 类型 长度 说明 transType 交易代码 Text 2 参见交易代码定义 result 交易结果 Text 4 参见返回代码定义 reserve 备用字段 Text 2 用于协议报按 32 位对齐 point 积分值 Text 10 扣减的积分值 4.3.3.3. 积分撤消(Cancel) 当积分消费交易成功后，因特殊原因（客户退货或营业员误操作等）需要 对成功的交易取消时，才可发起积分撤消交易。 4.3.3.3.1. Trans 命令的语法 字段名 字段含义 类型 长度 说明 transType 交易代码 Text 2 参见交易代码定义 transData 交易日期 Text 8 YYYYMMDD transTime 交易时间 Text 6 HHMMSS（24 小时制） transNo 交易流水号 Text 19 交易流水号 ref_transNo 原交易流水号 Text 19 需要撤消的原交易流水号 point 原交易积分值 Text 10 需要撤消的原交易话费值 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 18 页 共 33 页 md5_DES 数字摘要 Text 98 先由交易报文中 19位长的 “transNo”＋19位长的 “ref_transNo”＋10位长 “point”依次拼接组成的字符 串进行MD5 数字摘要得到字 符串 S1，然后对 S1 使用交易 密钥进行 DES 加密后得到字符 串 S2，此处存放的就是 S2 relatingNo 原交易手机号 Text 19 需要撤消的原交易手机号 reserve 备用字段 Text 3 用于协议报按 32 位对齐 4.3.3.3.2. Trans_Resp 应答的语法 字段名 字段含义 类型 长度 说明 transType 交易代码 Text 2 参见交易代码定义 result 交易结果 Text 4 参见返回代码定义 reserve 备用字段 Text 2 用于协议报按 32 位对齐 point 积分值 Text 10 原交易的积分值 4.3.3.4. 积分冲正(Corre) 冲正是对一笔正交易的反交易。当交易超时收不到应答时或其他原因交易出 现异常，系统应自动对原交易发起冲正。 4.3.3.4.1. Trans 命令的语法 字段名 字段含义 类型 长度 说明 transType 交易代码 Text 2 参见交易代码定义 transData 交易日期 Text 8 YYYYMMDD transTime 交易时间 Text 6 HHMMSS（24 小时制） transNo 交易流水号 Text 19 交易流水号 ref_transNo 原交易流水号 Text 19 需要冲正的原交易流水号 point 原交易积分值 Text 10 需要冲正的原交易话费值 md5_DES 数字摘要 Text 98 先由交易报文中 19位长的 “transNo”＋19位长的 “ref_transNo”＋10位长“point” 依次拼接组成的字符串进行 MD5 数字摘要得到字符串 S1，然 后对 S1 使用交易密钥进行DES 吉林移动手机支付系统交易网关接口规范 神州数码思特奇信息技术股份有限公司 第 19 页 共 33 页 加密后得到字符串 S2，此处存放 的就是 S2 relatingNo 原交易手机号 Text 19 需要冲正的原交易手机号 reserve 备用字段 Text 3 用于协议报按 32 位对齐 4.3.3.4.2. Trans_Resp 应答的语法 字段名 字段含义 类型 长度 说明 transType 交易代码 Text 2 参见交易代码定义 result 交易结果 Text 4 参见返回代码定义 reserve 备用字段 Text 2 用于协议报按 32 位对齐 point 积分值 Text 10 原交易的积分值 4.3.3.5. 话费查询(Query) 4.3.3.5.1. Trans 命令的语法 字段名 字段含义 类型 长度 说明 transType 交易代码 Text 2 参见交易代码定义 transData 交易日期 Text 8 YYYYMMDD transTime 交易时间 Text 6 HHMMSS（24 小时制） transNo 交易流水号 Text 19 交易流水号 rel