工行网上银行系统B2B商户(新接口)手册.doc

中国工商银行网上银行系统中国工商银行网上银行系统 B2BB2B 支付（新接口）支付（新接口） 中国工商中国工商银银行行软软件开件开发发中心中心 Copyright Reserved 2005 年年 8 月月 商户手册 网上银行商户手册 Copyright ICBC SDC 2005.8 - 1 - 1.文档属性 文档属性内容 文档名称：网上银行系统 B2B 商户(新接口)手册 文档版本号：1.3 文档状态：正式稿 文档编写完成日期2005-09 2.文档变更历史清单 文档版本号变更日期修改人变更内容简述 1.12005-12-20解志超之前通知消息编码方式是将 整个 http 请求的 bodycontent 进行了 URL 编码，不符合 http 协议的格式，不利于商 户端的开发。根据商户的建 议修改为：对请求中的每个 字段的值单独进行 URL 编码， 这样商户端可以更方便的取 到各个字段的值。 1.22006-06-06解志超修正了文档的一些错误 1.32006-10-25解志超请求接口中增加收款人名称 字段 网上银行商户手册 Copyright ICBC SDC 2005.8 - 2 - 前前 言言 该文档包括客户通过商户网站的中国工商银行网上银行的中国工商银行网上银行的“B2B 网上支付网上支付”URL 超链 进行 B2B 新接口网上支付时，商户必须向银行提供的部分订单信息及其格式；中国工商银 行向商户返回客户付款情况信息的内容、格式、验证签名程序的接口及调试用的例子。 网上银行商户手册 Copyright ICBC SDC 2005.8 - 3 - 目目 录录 前 言.2 目 录 3 1商户端的接口商户端的接口 .4 1.1 参数名及其内容列表4 1.2 商户请求中签名数据产生方法.5 1.3 一个链接例子.7 2银行反馈信息的接口银行反馈信息的接口 .8 2.1 通知消息接口数据格式：.8 2.2 通知消息的FORM格式： 10 2.3 通知消息处理过程.11 3.商户端系统环境要求商户端系统环境要求.13 3.1 软件环境.13 4.常见问题常见问题.13 问题 1 返回一个空白页面，页面中只有五位错误代码.13 问题 2 返回超时页面.14 网上银行商户手册 Copyright ICBC SDC 2005.8 - 4 - 1商户端的接口商户端的接口 客户通过商户的网站与卖方进行 b2b 网上定购交易，确认订单后通过商户 网站提供的“中国工商银行网上支付”超链，进入中国工商银行的网上支付画 面进行支付。为此商户网站必须将该订单中的部分信息以 Form 提交方式中的 Post 方法，将数据提交到中国工商银行指定的的网上支付 URL (https:/*.*.*.*/servlet/ICBCINBSEBusinessServlet，严格区分大小写，严格区分大小写,请联系所在地分请联系所在地分 行确认投产环境和测试环境的行确认投产环境和测试环境的 IP 地址地址)中。 1.1 参数名及其内容列表参数名及其内容列表 变量名称变量名称变量命名变量命名长度定义长度定义说明说明 接口名称APIName MAX (30) 必输，签名，上送“B2B”，区别大小写！ 接口版本号APIVersion =15 必输，签名,上送”001.001.001.001” 商户代码Shop_code =14 必输，签名，唯一确定一个商户的代码，商 户在工行开户时，由工行告知商户 支付结果信息 通知程序地址 MerchantURL MAX (200) 必输，签名，使用 HS 接口模式的商户用来接 收工行订单支付结果信息的程序名字和位置。 订单号ContractNo MAX(30) 必输，签名，客户支付后商户网站产生的一 个唯一的定单号，该订单号应该在相当长的 时间内不重复。工行通过订单号加订单日期 来唯一确认一笔订单的重复性。 订单金额ContractAmt MAX(18) 必输，签名，客户支付订单的总金额，一笔 订单一个，保留到分，无小数点，如金额为 1.00 元，上传数据为“100” 支付币种Account_cur = 3 必输，签名，用来区分一笔支付的币种。目 前工行只支持人民币（001）支付。定义如下： 001 人民币 检验联名标志JoinFlag必输，签名，固定上送 2 订单签名数据Mer_Icbc20_si gnstr 无限制必输，生成签名数据的方法见后面的说明 商城证书数据Cert无限制必输，商户端读取本地商户证书文件后，再 使用工行提供的 API 进行 Base64 编码后产生 的商户证书数据字串。 结果发送类型SendType =1 0 -成 功失败信 息都发送 1 - 必输，签名，如果取 0，工行向商户发送一 笔订单的每一次交易结果，无论支付成功或 者失败，如果取 1，工行只向商户发送交易 成功的通知信息。当在付款人一方 b2b 支付 指令经过指令批复后提交的，结果发送类型 网上银行商户手册 Copyright ICBC SDC 2005.8 - 5 - 只发送成 功信息 默认为成功失败都发送，这时不取商户上送 的发送类型。 交易日期时间TranTime =14 必输，签名，YYYYMMDDHHmmss。与工行系统 当前时间差为：前 1 小时，后 12 小时 商城账号Shop_acc_num MAX (19) 必输，签名 收款单位账号PayeeAcct MAX (19) 必输，签名 商品编号GoodsCode MAX (30) 选输 商品名称GoodsName MAX (60) 选输 订单数量Amount MAX (10) 选输 已含运费金额TransFee MAX (18) 选输 商城提示ShopRemark MAX (120) 选输，最多 120 字符 商城备注字段ShopRem MAX(100) 选输，最多 100 字符 收款人名称PayeeName MAX(60) 选输，最多 60 字符，30 个汉字 注意注意： 1. 从商户 Post 过来的数据，参数的名称必须与上表中完全相同，名称中的字母 大小写均要相同，不能进行随意更改(在 form 中的提交按钮中 submit 不能有 Name 属性)；此外，如果其他 input 项的 Name 中使用了双引号，如：，则一定注意在引号内不要包含空 格，不要写成“Merchant URL ”或者“ Mer chantURL” ，如果拼写错误或者多 了空格，将造成数据无法识别，无法正常进行支付。 2.接口名称和版本号一定要和上表中相同。 3.为了保证中文信息的正确性，商户请求的数据字符集要求是 GBK。 4.商户提交数据中的空格将被认为是有效字符被接收，请商户开发时注意对多 余空格的控制。 5.商户证书对于商城账号必须有定购操作权限，收款账号可以和商城账号不相 同，上送的商城账号与收款人账号相同时，则后续可提供退货、返还操作。如 果付款人有任意账号转账权限，那么收款账号可为任意的工行 19 位账号，否则 收款账号必须为付款人所在集团在网银注册的可收款的 19 位账号，此接口不支 持低于 19 位的老账号。 6.关于新增的收款人名称字段： 如果商户在这个字段上送了收款人名称那么客户在支付页面就不用输入了， 网上银行商户手册 Copyright ICBC SDC 2005.8 - 6 - 会取上送的收款人名称；如果商户没有上送那么会在商户所在企业网银集团所 有提交 id 的收款人名册（可以在企业网银的 付款业务-网上汇款-收款人名册 栏目中维护收款人名册）中查找是否有交易中的收款账号，如果有就会取收款 人名册的收款人名称，这时也不用客户输入收款人名称；如果以上两种情况都 不满足那么在支付页面就需要客户输入收款人名称。请商户根据自身情况选择 收款人名称的获得方式。 对于已经开发完成的商户不上送这个字段也可以继续使用接口，不会影响 已有功能。 1. 2 商户请求中签名数据产生方法商户请求中签名数据产生方法 签名信息字段签名信息字段 Mer_Icbc20_signstr 的产生的产生 通过调用工行提供的签名 API，用商户自己的私钥对交易数据和商户信息数据进行数 字签名，产生签名结果。步骤如下： 1组织要签名的数据串（串的顺序不可改变）组织要签名的数据串（串的顺序不可改变） 数据串为： APIName=B2B privateKey 为其私钥，长度为：keyLen keyPass 为私钥密码 网上银行商户手册 Copyright ICBC SDC 2005.8 - 7 - signBuf 为保存签名的缓冲区的指针，空间由 API 内部分配。签名后将签名 数据保存在此。指针空间的释放由应用程序负责。 signBufLen 存放签名数据的长度指针。 返回：0 正确，其它错误 JAVA 接口接口 byte sign( byte src, int srcLen, byte privateKey, char keyPass)。 参数说明： src 为需要签名的数据，长度为：srcLen; privateKey 为其私钥 keyPass 为私钥密码 返回： 成功：签名数据 失败：返回空(null) 注：src 源数据就是要进行签名的数据串信息。 3然后调用然后调用 BASE64 编码编码 API 对产生的签名数据编码，接口如下：对产生的签名数据编码，接口如下： C 接口接口 int base64enc(unsigned char *src, int srcLen, char *dst, int *dstLen) 参数说明： src 源数据，其长度为：srcLen; dst 为编码后的数据，长度存放在：dstLen dst 的存储空间由接口申请，应用释放 返回：0 正确，-1 错误 JAVA 接口：接口： byte base64enc(byte src) 参数说明： src 源数据 返回：正确 编码后数据，错误 null 注：src 源数据就是要进行 BASE64 编码的签名信息。 4签名信息产生完毕。签名信息产生完毕。 网上银行商户手册 Copyright ICBC SDC 2005.8 - 8 - 商户证书字段商户证书字段 cert 的的 BASE64 编码编码 对商户证书的 BASE64 编码与对签名信息的 BASE64 的编码一样，在此不在赘述。 1.3 一个链接例子一个链接例子 以下给出商户网站到中国工商银行网上银行的“网上支付”链接的 form 表单的例子（注意避免使用中文的全角符号） （form 不能有 name 属性） （若不正确，将无银行反馈信息，注意不能省略 http:/） （金额为不带小数点的到分 的一个字符串，即“112390”代表的是“1123.90 元” ） 网上银行商户手册 Copyright ICBC SDC 2005.8 - 9 - （金额为不带小数点的到分的一个字 符串，即“112390”代表的是“1123.90 元” ） 2银行反馈信息的接口银行反馈信息的接口 客户通过中国工商银行 B2B 支付新接口进行电子支付是实时清算的, 银 行需要经过收到支付信息余额确认划拨款项等环节才能将客户的款项划至 收款人帐户中。不论支付成功还是失败或者支付过程中发生错误，银行都会将 指令信息及时反馈给商户。目前 b2b 新接口只提供 URL 通知方式。 由交易的网站（一般是卖方或者中间的电子商城）提供一个 URL（Asp、Jsp、Java Bean 或者 CGI 等）供访问，我们使用 Form 提交方式将 所有数据提交给该 URL，并将银行的电子签名作为数据项，提交给商户网站。 2.1 通知消息接口数据格式：通知消息接口数据格式： 1. 编写编写 CGI 程序接收工行如下的程序接收工行如下的 http 请求请求 工行通知商户的交易结果信息的内容由订单信息和订单支付结果信息组成如下格式(各个数各个数 据项的值分别进行了据项的值分别进行了 URL 编码编码)： APIName=B2B dst 为编码后的数据，长度存放在：dstLen dst 的存储空间由接口申请，应用释放 返回：0 正确，-1 错误 JAVA 接口接口 byte base64dec(byte src) 参数说明： src 源数据 返回：正确 编码后数据，错误 null 4 调用调用 API 统一接口验证统一接口验证 BASE64 解码后得到的签名信息，接口如下：解码后得到的签名信息，接口如下： C 接口接口 int verifySign( char *src, int srcLen, unsigned char *cert, int certLen, 网上银行商户手册 Copyright ICBC SDC 2005.8 - 14 - unsigned char *signBuf, int signBufLen)。 参数说明： src 为原始数据，其长度为：srcLen; cert 为签名者的证书，长度为：certLen signBuf 为签名数据，长度为：signBufLen。 返回：0 正确，1 错误 JAVA 接口接口 int verifySign(byte src, int srcLen, byte cert, byte sign)。 参数说明： src 为原始数据，长度为:srcLen; cert 为签名者的证书 sign 为签名数据 返回： 成功：0 失败：其