工行b2c
B2C支付接口v1.0.0.11
中国工商银行软件开发中心
Copyright Reserved
目录
第 1 章 业务说明
以下简述处理流程：
1.客户在商户网站浏览商品信息，签订订单；
2.商户按照工行B2C支付1.0.0.11接口形成提交数据，并使用工行提供API和商户证书对订单数据签名，形成form表单返回客户浏览器，表单action地址指向工行接收商户订单信息的servlet；
3.客户确认使用工行支付后，提交此表单到工行；
4.工行网银系统接收此笔订单，对订单信息和商户信息进行检查；
5.通过检查则显示工行支付页面，1.0.0.11版本会提示客户输入交易卡号；
6.客户输入后提交；
7.银行查询客户相关信息；
8.返回客户在银行的预留信息；
9.客户确认；
10.返回交易确认页面；
11.不同类型客户使用各自认证方式进行交易确认，支持静态支付密码、动态口令卡、证书签名；
12.银行校验后进行支付处理；
13.工行进行支付指令处理后，如果商户需要工行实时通知，则工行将处理结果使用http协议post方式将通知消息数据提交到商户网站（这个接收银行通知消息的商户端地址是随商户订单数据提交银行的merURL字段），商户返回取货地址或关闭这个银行与其建立的连接后，银行才显示交易结果页面给客户。（注意1、发送通知和显示结果页面是串行的，所以商户端接收银行通知处理时间太长可能导致客户等待超时，造成银行不能将交易结果页面显示给客户。2、此连接是银行服务器自动和商户进行的连接，商户返回也是直接返回给银行，商户端不能对银行的这个请求进行重定向。）
14.工行进行支付指令处理后，如果商户不需要工行实时通知，则工行直接显示交易结果给客户。
B2C在线支付接口版本说明：
1.0.0.0（基本支付）
1.0.0.1（支持中英文界面）
1.0.0.2（内部保留）
1.0.0.3（保留1.0.0.1功能，优化通知方式）
1.0.0.4（商户订单中指定支付卡，不强制使用e卡支付，不允许客户的支付卡透支支付，专门用于基金商户进行基金直销业务，同1.0.0.3通知方式）
1.0.0.5（基于1.0.0.1，在原有接口基础上扩展支持红利卡，支持红利卡的商户采用；当上送项不支持红利卡的时候，接口等同于1.0.0.1）
1.0.0.6（基于1.0.0.3，在原有接口基础上扩展支持红利卡，支持红利卡的商户采用；当上送项不支持红利卡的时候，接口等同于1.0.0.3）
1.0.0.7（基于1.0.0.3，在原有接口基础上扩展支持同时上送5笔订单，即支持购物车模式，支持商户主动分期付款模式，当商户选择1期和1笔订单的时候，功能等同于1.0.0.3接口）
1.0.0.8（基于1.0.0.3，在原有接口基础上扩展，根据商户上送的是否允许透支标志来控制是否运行客户使用信用卡进行支付，同1.0.0.3通知方式）
1.0.0.9（基于1.0.0.3，在原有接口基础上优化商户校验及接口并发性，同1.0.0.0通知方式）
1.0.0.10（基于1.0.0.8，同1.0.0.0通知方式）
1.0.0.11（基于1.0.0.7，在原有接口基础上增加1.0.0.8的透支标志控制，增加商户上送数据,丰富及扩展用户体验，增加校验商户域名，同1.0.0.0通知方式）
第 2 章 商户接口
2.1支付接口
2.1.1支付接口表单定义
新模式接口的交易数据整合到一个xml格式串，作为表单的一项整体提交，不再同原来每个字段都是key-value形式；
FORM表单数据如下：
变量名称 | 变量命名 | 长度定义 | 说明 |
|---|---|---|---|
接口名称 | interfaceName | MAX(30) | 必输， 取值：“ICBC_PERBANK_B2C” |
接口版本号 | interfaceVersion | MAX(15) | 必输， 取值：“1.0.0.11” |
交易数据 | tranData | 无限制 | 必输，签名； 整合所有交易数据形成的xml明文串，并做BASE64编码； 具体格式定义见下文； 注意： 需有xml头属性；整个字段使用BASE64编码； xml明文中没有回车换行和多余空格； |
订单签名数据 | merSignMsg | 无限制 | 必输， 商户使用工行提供的签名API和商户证书将tranData的xml明文串进行签名，得到二进制签名数据，然后进行BASE64编码后得到可视的merSignMsg； 注意：签名时是针对tranData的xml明文，不是将tranData进行BASE64编码后的串； |
商城证书公钥 | merCert | 无限制 | 必输， 商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串； |
注：
1、数据中不能包含“|”、“&”、“=”，这些字符为银行端程序保留字符；中文变量使用GBK编码。
2、从商户Post过来的数据，参数名的名称必须与上表中完全相同，名称中的字母大小写均要相同，不能进行随意更改(在form中的提交按钮<input type=”submit”……>中submit不能有Name属性)；此外，如果其他input 项的Name中使用了双引号，如：<input type=text name=" merCert " value="xxxxxxx">，则一定注意在引号内不要包含空格，不要写成“mer URL ”，如果拼写错误或者多了空格，将造成数据无法识别，无法正常进行支付
3、接口名称和版本号一定要和上表中相同.。
4、商户提交数据中的空格将被认为是有效字符被接收，请商户开发时注意对多余空格的控制。
5、tranData交易数据的xml串需要有xml的头，即<?xml version="1.0" encoding="GBK" standalone="no"?>
2.1.2tranData数据定义
变量名称 | 变量命名 | 长度定义 | 说明 |
|---|---|---|---|
接口名称 | interfaceName | ＝16 | 必输， 取值：“ICBC_PERBANK_B2C” |
接口版本号 | interfaceVersion | MAX(15) | 必输， 取值：“1.0.0.11” |
交易日期时间 | orderDate | =14 | 必输， 格式为：YYYYMMDDHHmmss 目前要求在银行系统当前时间的前后十分钟范围内，否则判定交易时间非法。 |
订单号 | orderid | MAX(30) | 必输，每笔订单都需要有不同的订单号； 客户支付后商户网站产生的一个唯一的订单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。 若该笔订单为招投标订单（orderFlag_ztb上送1），则该字段上送约定的招投标缴纳编号（长度MAX(20)） |
订单金额 | amount | MAX(10) | 必输，每笔订单一个； 客户支付订单的总金额，一笔订单一个，以分为单位。不可以为零，必需符合金额标准。 |
分期付款期数 | installmentTimes | MAX（2） | 必输，每笔订单一个； 取值：1、3、6、9、12、18、24；1代表全额付款，必须为以上数值，否则订单校验不通过。 |
商户账号 | merAcct | MAX(29) | 必输，每笔订单一个，可以相同； 商户入账账号，只能交易时指定。（商户付给银行手续费的账户，可以在开户的时候指定，也可以用交易指定方式；用交易指定方式则使用此商户账号）。支持上送19位账号或19-9格式账号（19位主账号-9位子账户序号） |
商品编号 | goodsID | MAX(30) | 选输，每笔订单一个； |
商品名称 | goodsName | MAX(60) | 必输，每笔订单一个； |
商品数量 | goodsNum | MAX(10) | 选输，每笔订单一个； |
已含运费金额 | carriageAmt | MAX(10) | 选输，每笔订单一个； 注：银行支付页面不会向客户显示该项内容。 |
检验联名标志 | verifyJoinFlag | =1 | 必输， 取值“1”：客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误；我行联名商户可送“1”； 取值“0”：不检验客户是否与商户联名，按上送金额扣帐。非联名商户请送“0”； |
语言版本 | Language | MAX(10) | 选输，默认为中文版 取值：“EN_US”为英文版； 取值：“ZH_CN”或其他为中文版。 注意：大小写敏感。 |
支付币种 | curType | = 3 | 必输， 用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。 取值： “001” |
商户代码 | merID | MAX(20) | 必输， 唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。 |
支持订单支付的银行卡种类 | creditType | = 1 | 必输 默认“2”。取值范围为0、1、2，其中0表示仅允许使用借记卡支付，1表示仅允许使用信用卡支付，2表示借记卡和信用卡都能对订单进行支付 |
通知类型 | notifyType | = 2 | 必输 在交易转账处理完成后把交易结果通知商户的处理模式。 取值“HS”：在交易完成后实时将通知信息以HTTP协议POST方式，主动发送给商户，发送地址为商户端随订单数据提交的接收工行支付结果的URL即表单中的merURL字段； 取值“AG”：在交易完成后不通知商户。商户需使用浏览器登录工行的B2C商户服务网站，或者使用工行提供的客户端程序API主动获取通知信息。 取值“TS”：在交易完成后实时将通知信息以HTTP协议POST方式，主动发送给商户，发送地址为商户端随订单数据提交的接收工行支付结果的URL即表单中的merURL字段，商户响应银行通知时返回取货链接给工行，如工行未收到商户响应则重复发送通知消息，发送次数由工行参数配置。 |
结果发送类型 | resultType | =1 | 选输 取值“0”：无论支付成功或者失败，银行都向商户发送交易通知信息； 取值“1”，银行只向商户发送交易成功的通知信息。 只有通知方式为HS时此值有效，如果使用AG方式，可不上送此项，但签名数据中必须包含此项，取值可为空。 |
商户reference | merReference | MAX(200) | 选输，上送商户网站域名（例如：pay.某B2C商城.com），支持首字段通配符（例如：*.某B2C商城.com）。 如果上送，工行会在客户支付订单时，校验商户上送域名与客户跳转工行支付页面之前网站域名的一致性。 |
客户端IP | merCustomIp | MAX(20) | 选输，工行在支付页面显示该信息。 注意： 1、使用IPV4格式。 2、上送的是客户端的公网IP。 3、当商户reference项送空时，该项必输。 4、如果使用代理服务器发送请求，需要上送代理服务器的IP。 |
虚拟商品/实物商品标志位 | goodsType | =1 | 选输，若输入： 取值“0”：虚拟商品； 取值“1”，实物商品。 |
买家用户号 | merCustomID | MAX(100) | 选输，工行在支付页面显示该信息。 |
买家联系电话 | merCustomPhone | MAX(20) | 选输，工行在支付页面显示该信息。 |
收货地址 | goodsAddress | MAX(200) | 选输，工行在支付页面显示该信息。 |
订单备注 | merOrderRemark | MAX(200) | 选输，工行在支付页面显示该信息。 |
商城提示 | merHint | MAX(120) | 选输 |
备注字段1 | remark1 | MAX(100) | 选输 单位：字节 |
备注字段2 | remark2 | MAX(100) | 选输 单位：字节 |
返回商户URL | merURL | MAX(1024) | 必输 必须合法的URL，交易结束，将客户引导到商户的此url，即通过客户浏览器post交易结果信息到商户的此URL，该URL支持http以及https协议。 |
成功页自动跳转商户倒计时参数 | autoReferSec | MAX(60) | 选输 当商户返回的商城取货地址为正常可达时，如该参数非空，则倒计时结束后自动跳转回商城取货地址对应链接，如不上送则默认不自动跳转。 |
返回商户变量 | merVAR | MAX(1024) | 选输 商户自定义，当返回银行结果时，作为一个隐藏域变量，商户可以用此变量维护session等等。由客户端浏览器支付完成后提交通知结果时是明文传输，建议商户对此变量使用额外安全防范措施，如签名、base64 |
支付通知是否支持优惠信息 | isSupportDISCOUFlag | 0-不支持 1-支持 | 选输， 如商户需要在工行返回的通知消息结果中包含优惠信息的内容，则该字段送1-支持 |
工银e支付注册标志 | e_isMerFlag | =1 | 选输 工银e支付注册标志，标识客户在支付该笔订单时，是否使用订单指定的下述信息注册工银e支付。 0-否，1-是 |
客户姓名 | e_Name | MAX(30) | 选输，e_isMerFlag送1时有效 |
客户手机号 | e_TelNum | =11 | 选输，e_isMerFlag送1时有效 如果工银e支付注册标志e_isMerFlag上送1，则此字段必输 |
客户证件类型 | e_CredType | MAX(2) | 选输，e_isMerFlag送1时有效 0:身份证 1:护照 2:军官证 3:士兵证 4:回乡证（港澳台往来通行证） 5:临时身份证 6:户口本 7:其他 9:警官证 12:外国人永久居住证 21:边民证 |
客户证件号 | e_CredNum | MAX(18) | 选输，e_isMerFlag送1时有效 |
待注册工银e支付的卡/账号 | e_CardNo | MAX(19) | 选输，e_isMerFlag送1时有效 如上送，则按指定的账户进行工银e支付注册 |
招投标订单标志 | orderFlag_ztb | =1 | 选输，0-否，1-是 如该标志上送1，则仅支持上送一笔订单，且订单号字段orderid需上送约定的招投标缴纳编号（长度MAX(20)） |
注：
1）红色字体部分内容，每笔订单都有一份；
2）如商户已在工行系统开通银联支付功能，且希望订单可以使用银联支付，则上送的订单信息需满足如下条件：
a)订单号orderid长度不小于12位，且不包含-、_等连接符；
b)检验联名标志verifyJoinFlag送“0”；
c)仅上送单笔订单信息（如下2.1.3节tranData格式定义中，subOrderInfoList结构中仅包含一个subOrderInfo域）；
d)分期付款期数installmentTimes上送“1”；
e)支持订单支付的银行卡种类creditType上送2-不限定支付卡类型。
2.1.3tranData格式定义
tranData格式(xml格式固定，选输字段的取值可以为空，标签需保留)
<?xml version="1.0" encoding="GBK" standalone="no"?>
<B2CReq>
<interfaceName>ICBC_PERBANK_B2C</interfaceName>
<interfaceVersion>1.0.0.11</interfaceVersion>
<orderInfo>
<orderDate>20100308141629</orderDate>
<curType>001</curType>
<merID>0200EC20001119</merID>
<subOrderInfoList>
<subOrderInfo>
<orderid>201003081416290</orderid>
<amount>1</amount>
<installmentTimes>1</installmentTimes>
<merAcct>0200026009018372212</merAcct>
<goodsID>001</goodsID>
<goodsName>威尼熊</goodsName>
<goodsNum>2</goodsNum>
<carriageAmt>20</carriageAmt>
</subOrderInfo>
<subOrderInfo>
<orderid>201003081416291</orderid>
<amount>1</amount>
<installmentTimes>1</installmentTimes>
<merAcct>0200026009018372212</merAcct>
<goodsID>001</goodsID>
<goodsName>威尼熊</goodsName>
<goodsNum>2</goodsNum>
<carriageAmt>20</carriageAmt>
</subOrderInfo>
</subOrderInfoList>
</orderInfo>
<custom>
<verifyJoinFlag>0</verifyJoinFlag>
<Language>ZH_CN</Language>
</custom>
<message>
<creditType>2</creditType>
<notifyType>AG</notifyType>
<resultType>1</resultType>
<merReference>localhost</merReference>
<merCustomIp>127.0.0.1</merCustomIp>
<goodsType>1</goodsType>
<merCustomID>123456</merCustomID>
<merCustomPhone>13466780886</merCustomPhone>
<goodsAddress>三里屯</goodsAddress>
<merOrderRemark>防欺诈接口专用</merOrderRemark>
<merHint>请保留包装</merHint>
<remark1></remark1>
<remark2></remark2>
<merURL>http://localhost:80/EbizSimulate/emulator/Newb2c_Pay_Mer.jsp</merURL>
<autoReferSec>5</autoReferSec>
<merVAR>test</merVAR>
<isSupportDISCOUFlag>1</isSupportDISCOUFlag>
</message>
<extend>
<e_isMerFlag>1</e_isMerFlag>
<e_Name>屿鸦顶</e_Name>
<e_TelNum>13814444444</e_TelNum>
<e_CredType>0</e_CredType>
<e_CredNum>128568580210620</e_CredNum>
<e_CardNo>9558880200005170880</e_CardNo>
<orderFlag_ztb>0</orderFlag_ztb>
</extend>
</B2CReq>
注：红色字体部分，即<subOrderInfo>是循环部分，最大5次，超过则接口校验报错。
2.1.4表单样例
表单数据：
<INPUT NAME="interfaceName" TYPE="text" value="ICBC_PERBANK_B2C" >
<INPUT NAME="interfaceVersion" TYPE="text" value="1.0.0.11">
<INPUT NAME="tranData" TYPE="text" value="PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iR0JLIiBzdGFuZGFsb25lPSJubyI/PjxCMkNSZXE+PGludGVyZmFjZU5hbWU+SUNCQ19QRVJCQU5LX0IyQzwvaW50ZXJmYWNlTmFtZT48aW50ZXJmYWNlVmVyc2lvbj4xLjAuMC4xMTwvaW50ZXJmYWNlVmVyc2lvbj48b3JkZXJJbmZvPjxvcmRlckRhdGU+MjAxNDA5MjkxMjIyMDE8L29yZGVyRGF0ZT48Y3VyVHlwZT4wMDE8L2N1clR5cGU+PG1lcklEPjAyMDBFQzIzNDk3Njk2PC9tZXJJRD48c3ViT3JkZXJJbmZvTGlzdD48c3ViT3JkZXJJbmZvPjxvcmRlcmlkPjIwMTQwOTI5MTIyMjAxMDwvb3JkZXJpZD48YW1vdW50PjE5ODA8L2Ftb3VudD48aW5zdGFsbG1lbnRUaW1lcz4xPC9pbnN0YWxsbWVudFRpbWVzPjxtZXJBY2N0PjAyMDAwODA5MDkyMDAxMDA1NTQ8L21lckFjY3Q+PGdvb2RzSUQ+MDAxPC9nb29kc0lEPjxnb29kc05hbWU+zf7E4dDcPC9nb29kc05hbWU+PGdvb2RzTnVtPjI8L2dvb2RzTnVtPjxjYXJyaWFnZUFtdD4wPC9jYXJyaWFnZUFtdD48L3N1Yk9yZGVySW5mbz48L3N1Yk9yZGVySW5mb0xpc3Q+PC9vcmRlckluZm8+PGN1c3RvbT48dmVyaWZ5Sm9pbkZsYWc+MDwvdmVyaWZ5Sm9pbkZsYWc+PExhbmd1YWdlPlpIX0NOPC9MYW5ndWFnZT48L2N1c3RvbT48bWVzc2FnZT48Y3JlZGl0VHlwZT4yPC9jcmVkaXRUeXBlPjxub3RpZnlUeXBlPkFHPC9ub3RpZnlUeXBlPjxyZXN1bHRUeXBlPjA8L3Jlc3VsdFR5cGU+PG1lclJlZmVyZW5jZT44Mi4yMDAuNDUuMTc2PC9tZXJSZWZlcmVuY2U+PG1lckN1c3RvbUlwPjEyNy4wLjAuMTwvbWVyQ3VzdG9tSXA+PGdvb2RzVHlwZT4xPC9nb29kc1R5cGU+PG1lckN1c3RvbUlEPjEyMzQ1NjwvbWVyQ3VzdG9tSUQ+PG1lckN1c3RvbVBob25lPjEzNDY2NzgwODg2PC9tZXJDdXN0b21QaG9uZT48Z29vZHNBZGRyZXNzPsj9wO/NzTwvZ29vZHNBZGRyZXNzPjxtZXJPcmRlclJlbWFyaz63wMbb1am907/a16jTwzwvbWVyT3JkZXJSZW1hcms+PG1lckhpbnQ+x+uxo8H0sPzXsDwvbWVySGludD48cmVtYXJrMT48L3JlbWFyazE+PHJlbWFyazI+PC9yZW1hcmsyPjxtZXJVUkw+aHR0cDovLzgyLjIwMC40NS4yMDEvZW11bGF0b3IvTWVyUmV0dXJuLmpzcDwvbWVyVVJMPjxtZXJWQVI+dGVzdDwvbWVyVkFSPjwvbWVzc2FnZT48ZXh0ZW5kPjxlX2lzTWVyRmxhZz4xPC9lX2lzTWVyRmxhZz48ZV9OYW1lPtPs0bu2pTwvZV9OYW1lPjxlX1RlbE51bT4xMzgxNDQ0NDQ0NDwvZV9UZWxOdW0+PGVfQ3JlZFR5cGU+MDwvZV9DcmVkVHlwZT48ZV9DcmVkTnVtPjEyODU2ODU4MDIxMDYyMDwvZV9DcmVkTnVtPjxlX0NhcmRObz45NTU4ODgwMjAwMDA1MTcwODgwPC9lX0NhcmRObz48L2V4dGVuZD48L0IyQ1JlcT4=">
<INPUT NAME="merSignMsg" TYPE="text" value="bgWUfKU1SzKjsr6A5FRf2iEHe/+/Cu58klm/36nNUzwTB2JmBUXesQJVOswjRIf3AzpZetCwMqvnuoAnX0u6WtnQIDAxZAR9TWFvNdmzA4uJxqbwMy6ruhLnqgCeWaVYzbD1gTZ6ndMd4/gBXTbKnT9/YezPKHSP348u+0f0j8A=">
<INPUT NAME="merCert" TYPE="text" value="MIIDCTCCAfGgAwIBAgIKbaHKEE0tAAAVmTANBgkqhkiG9w0BAQUFADA3MRowGAYDVQQDExFjb3JiYW5rMTAzIHNkYyBDTjEZMBcGA1UEChMQY29yYmFuazQzLmNvbS5jbjAeFw0xMzA2MDEwNjE5NTFaFw0xNDA2MDEwNjE5NTFaMEAxFDASBgNVBAMTC0xMTEwuZS4wMjAwMQ0wCwYDVQQLEwQwMjAwMRkwFwYDVQQKExBjb3JiYW5rNDMuY29tLmNuMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDUebVQUS8jnDERJopOwNgRlKEafEQUryj9EV64TUsaR850v/3KnctPRJ09GCqeucvbbOXlHz/RlwJSVWqryCTOldOUv1F58KQ0C59sY/dhh+W57fLIQKO90Sd344o/fPiytqmGtBc2m+DE/3L6morgC8m05Ygm16MkIk89Nz184wIDAQABo4GRMIGOMB8GA1UdIwQYMBaAFKnyXV7yfyOkd7D4zZtPLyquqLWdMEwGA1UdHwRFMEMwQaA/oD2kOzA5MQ0wCwYDVQQDEwRjcmw2MQ0wCwYDVQQLEwRjY3JsMRkwFwYDVQQKExBjb3JiYW5rNDMuY29tLmNuMB0GA1UdDgQWBBTkDBRsd9NghIrtNaUe6gSxZQ9CfzANBgkqhkiG9w0BAQUFAAOCAQEAXTWymvrTDMgV9LK7Ps6o52mlZIPmp3n7hmZttgJR/6KmZ/uCChPqHd9Ixw3DBnzHvoxmgtCKNVNc+iYQ4ks8cZgQoQ3uKT9bYinRCgECOv0Hiv7Q63DHJB46QamYcPc9dmmKAAOMd5AtnKI8QBRG3kxEmD6DPAcyx7hZ9Iw0MVwu4J1RfByJ1kM/bnhFpGwTma+5kxQlP+8Zurx4Cow/TUIj+kiLa/1ZmKXok7XOUr1UTFJhIqe0v3w2ekidchVML/t6n6Yw8Q5UCAbvKP4iHWdxeEGYsn+/a38oqCqIya66d5FCUqcOXXdRTdwdaSg6IGA4X6//O9TCvle1SCn7LQ==">
tranData对应的xml明文：
<?xml version="1.0" encoding="GBK" standalone="no"?><B2CReq><interfaceName>ICBC_PERBANK_B2C</interfaceName><interfaceVersion>1.0.0.11</interfaceVersion><orderInfo><orderDate>20140929122201</orderDate><curType>001</curType><merID>0200EC23497696</merID><subOrderInfoList><subOrderInfo><orderid>201409291222010</orderid><amount>1980</amount><installmentTimes>1</installmentTimes><merAcct>0200080909200100554</merAcct><goodsID>001</goodsID><goodsName>威尼熊</goodsName><goodsNum>2</goodsNum><carriageAmt>0</carriageAmt></subOrderInfo></subOrderInfoList></orderInfo><custom><verifyJoinFlag>0</verifyJoinFlag><Language>ZH_CN</Language></custom><message><creditType>2</creditType><notifyType>AG</notifyType><resultType>0</resultType><merReference>82.200.45.176</merReference><merCustomIp>127.0.0.1</merCustomIp><goodsType>1</goodsType><merCustomID>123456</merCustomID><merCustomPhone>13466780886</merCustomPhone><goodsAddress>三里屯</goodsAddress><merOrderRemark>防欺诈接口专用</merOrderRemark><merHint>请保留包装</merHint><remark1></remark1><remark2></remark2><merURL>http://82.200.45.201/emulator/MerReturn.jsp</merURL><autoReferSec>5</autoReferSec><merVAR>test</merVAR></message><extend><e_isMerFlag>1</e_isMerFlag><e_Name>屿鸦顶</e_Name><e_TelNum>13814444444</e_TelNum><e_CredType>0</e_CredType><e_CredNum>128568580210620</e_CredNum><e_CardNo>9558880200005170880</e_CardNo></extend></B2CReq>
2.2通知接口
2.2.1通知接口表单定义
变量名称 | 变量命名 | 长度定义 | 说明 |
|---|---|---|---|
返回商户变量 | merVAR | 无限制 | 取值：商户提交接口中merVAR字段当返回银行结果时，作为一个隐藏域变量，商户可以用此变量维护session等等。由客户端浏览器支付完成后提交通知结果时是明文传输，建议商户对此变量使用额外安全防范措施，如签名、base64，银行端将此字段原样返回 |
通知结果数据 | notifyData | 无限制 | 银行通知消息，xml格式定义见下文，提交商户时对xml明文串进行了base64编码； xml串中没有回车换行和多余空格；包含xml头属性，且格式固定； |
银行对通知结果的签名数据 | signMsg | 无限制 | 银行使用自己证书对商户通知消息notifyData字段的xml格式明文串进行的签名，然后进行BASE64编码后的字符串。 注意：签名是对notifyData的xml明文进行签名，不是其BASE64编码后的串；签名后得到二进制数据，对此数据进行BASE64编码得到signMsg |
2.2.2notifyData数据定义
变量名称 | 变量命名 | 长度定义 | 说明 |
|---|---|---|---|
接口名称 | interfaceName | ＝16 | 取值：“ICBC_PERBANK_B2C” |
接口版本号 | interfaceVersion | MAX(15) | 取值：“1.0.0.11” |
交易日期时间 | orderDate | =14 | 格式为：YYYYMMDDHHmmss 要求在银行系统当前时间的前1小时和后12小时范围内，否则判定交易时间非法。 |
订单号 | orderid | MAX(30) | 客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。工行通过订单号加订单日期来唯一确认一笔订单的重复性。 |
实际支付金额 | amount | MAX(10) | 客户支付订单的实际支付金额，一笔订单一个，以分为单位。不可以为零，必需符合金额标准。 |
分期付款期数 | installmentTimes | MAX（2） | 必输，每笔订单一个； 取值：1、3、6、9、12、18、24；1代表全额付款，必须为以上数值，否则订单校验不通过。 |
商户账号 | merAcct | MAX(19) | 商户收费入账账号 （只能交易时指定）。 |
银行指令序号 | tranSerialNo | MAX(30) | 银行端指令流水号 |
支付币种 | curType | = 3 | 用来区分一笔支付的币种，目前工行只支持使用人民币（001）支付。 取值： “001” |
商户代码 | merID | MAX(20) | 唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。 |
检验联名标志 | verifyJoinFlag | =1 | 取值“1”：客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误； 取值“0”：不检验客户是否与商户联名，按上送金额扣帐。 |
客户联名标志 | JoinFlag | =1 | 客户在银行端是否与商城联名标志位。1客户联名 0客户未联名 |
联名会员号 | UserNum | MAX(40) | 联名客户在商户的会员号。 |
批次号 | TranBatchNo | MAX(15) | 银行端为多笔一次提交的指令生成一个唯一的批次号 |
返回通知日期时间 | notifyDate | MAX(14) | 格式为：YYYYMMDDHHmmss |
订单处理状态 | tranStat | =1 | 1-“交易成功，已清算”； 2-“交易失败”； 3-“交易可疑” |
错误描述 | comment | MAX(100) | 错误描述 |
工银e支付注册支付结果 | epayRegResult | =1 | 订单指定e支付注册（e_isMerFlag上送1）时返回包含该字段； 客户是否使用订单指定信息完成工银e支付注册并支付订单，1-是，2-否 |
银行优惠金额 | bankDiscount | MAX(10) | isSupportDISCOUFlag为1是才返回；支持优惠的订单，银行优惠金额 |
商户优惠金额 | shopDiscount | MAX(10) | isSupportDISCOUFlag为1是才返回；支持优惠的订单，商户优惠金额 |
是否随机立减 | freeDisFlag | =1 | isSupportDISCOUFlag为1是才返回；0-否，1-是 |
注：红色字体部分内容，每笔订单都有一份。
2.2.3notifyData格式定义
notifyData格式(xml格式固定，选输字段的取值可以为空，标签需保留)
<?xml version="1.0" encoding="GBK" standalone="no"?>
<B2CRes>
<interfaceName></interfaceName>
<interfaceVersion></interfaceVersion>
<orderInfo>
<orderDate></orderDate>
<curType></curType>
<merID></merID>
<subOrderInfoList>
<subOrderInfo>
<orderid></orderid>
<amount></amount>
<installmentTimes></installmentTimes>
<merAcct></merAcct>
<tranSerialNo></tranSerialNo>
</subOrderInfo>
……
<subOrderInfo>
<orderid></orderid>
<amount></amount>
<installmentTimes></installmentTimes>
<merAcct></merAcct>
<tranSerialNo></tranSerialNo>
</subOrderInfo>
</subOrderInfoList>
</orderInfo>
<custom>
<verifyJoinFlag></verifyJoinFlag>
<JoinFlag></JoinFlag>
<UserNum></UserNum>
</custom>
<bank>
<TranBatchNo></TranBatchNo>
<notifyDate></notifyDate>
<tranStat></tranStat>
<comment></comment>
</bank>
<extend>
<epayRegResult></epayRegResult>
<bankDiscount></bankDiscount>
<shopDiscount></shopDiscount>
<freeDisFlag></freeDisFlag>
</extend>
</B2CRes>
注：红色字体部分，即<subOrderInfo>是循环部分，最大5次，根据商户上送的数量返回。高亮标黄字体部分为上送上送表单中isSupportDISCOUFlag1时才返回否则不返回
2.2.4表单样例
表单数据：
<INPUT TYPE="hidden" NAME="merVAR" VALUE="test">
<INPUT TYPE="hidden" NAME="notifyData" VALUE="PD94bWwgIHZlcnNpb249IjEuMCIgZW5jb2Rpbmc9IkdCSyIgc3RhbmRhbG9uZT0ibm8iID8+PEIyQ1Jlcz48aW50ZXJmYWNlTmFtZT5JQ0JDX1BFUkJBTktfQjJDPC9pbnRlcmZhY2VOYW1lPjxpbnRlcmZhY2VWZXJzaW9uPjEuMC4wLjExPC9pbnRlcmZhY2VWZXJzaW9uPjxvcmRlckluZm8+PG9yZGVyRGF0ZT4yMDEwMDkwMTE2MjE0Mjwvb3JkZXJEYXRlPjxjdXJUeXBlPjAwMTwvY3VyVHlwZT48bWVySUQ+MDIwMEVDMjAwMDExMTk8L21lcklEPjxzdWJPcmRlckluZm9MaXN0PjxzdWJPcmRlckluZm8+PG9yZGVyaWQ+MjAxMDA5MDExNjIxNDIwPC9vcmRlcmlkPjxhbW91bnQ+MTAwPC9hbW91bnQ+PGluc3RhbGxtZW50VGltZXM+MTwvaW5zdGFsbG1lbnRUaW1lcz48bWVyQWNjdD4wMjAwMDI2MDA5MDE4MzcyMjEyPC9tZXJBY2N0Pjx0cmFuU2VyaWFsTm8+SEZHMDAwMDAwMDAwMDAwNDIxPC90cmFuU2VyaWFsTm8+PC9zdWJPcmRlckluZm8+PHN1Yk9yZGVySW5mbz48b3JkZXJpZD4yMDEwMDkwMTE2MjE0MjE8L29yZGVyaWQ+PGFtb3VudD4xMjA8L2Ftb3VudD48aW5zdGFsbG1lbnRUaW1lcz4xPC9pbnN0YWxsbWVudFRpbWVzPjxtZXJBY2N0PjAyMDAwMjYwMDkwMTgzNzIyMTI8L21lckFjY3Q+PHRyYW5TZXJpYWxObz5IRkcwMDAwMDAwMDAwMDA0MjI8L3RyYW5TZXJpYWxObz48L3N1Yk9yZGVySW5mbz48L3N1Yk9yZGVySW5mb0xpc3Q+PC9vcmRlckluZm8+PGN1c3RvbT48dmVyaWZ5Sm9pbkZsYWc+MDwvdmVyaWZ5Sm9pbkZsYWc+PEpvaW5GbGFnPjwvSm9pbkZsYWc+PFVzZXJOdW0+PC9Vc2VyTnVtPjwvY3VzdG9tPjxiYW5rPjxUcmFuQmF0Y2hObz4wMDAwMDAwMDAwMDAwOTg8L1RyYW5CYXRjaE5vPjxub3RpZnlEYXRlPjIwMTAwOTEwMTc0MDUwPC9ub3RpZnlEYXRlPjx0cmFuU3RhdD4xPC90cmFuU3RhdD48Y29tbWVudD69u9LXs8m5pqOhPC9jb21tZW50PjwvYmFuaz48L0IyQ1Jlcz4=">
<INPUT TYPE="hidden" NAME="signMsg" VALUE="auCDrEmFk0Hr0ItAsNZwL0CZD6LEpI/WKm/SMc1mnlZNZ8Hx4iZS1P1c+DrXG67BKh60YhcdjVyko18BN9k4QpVBMAsuRl57wffkMm8rNubS4foCyXhKN3RRjYwtu8lrxvGHvLWPNJv+eMjyrIoHUH5ZQYGuZYQGcY2iz+IldaY=">
notifyData对应的明文：
<?xml version="1.0" encoding="GBK" standalone="no" ?><B2CRes><interfaceName>ICBC_PERBANK_B2C</interfaceName><interfaceVersion>1.0.0.11</interfaceVersion><orderInfo><orderDate>20100901162142</orderDate><curType>001</curType><merID>0200EC20001119</merID><subOrderInfoList><subOrderInfo><orderid>201009011621420</orderid><amount>100</amount><installmentTimes>1</installmentTimes><merAcct>0200026009018372212</merAcct><tranSerialNo>HFG000000000000421</tranSerialNo></subOrderInfo><subOrderInfo><orderid>201009011621421</orderid><amount>120</amount><installmentTimes>1</installmentTimes><merAcct>0200026009018372212</merAcct><tranSerialNo>HFG000000000000422</tranSerialNo></subOrderInfo></subOrderInfoList></orderInfo><custom><verifyJoinFlag>0</verifyJoinFlag><JoinFlag></JoinFlag><UserNum></UserNum></custom><bank><TranBatchNo>000000000000098</TranBatchNo><notifyDate>20100910174050</notifyDate><tranStat>1</tranStat><comment>交易成功！</comment></bank></B2CRes>
2.3说明
商户可能收到的银行通知
指令成功：
只能有一笔成功、且要验证银行签名、订单金额等信息是否与商户端记录一致。
指令失败：
商户只能收到一笔客户放弃支付返回商城的信息。
指令可疑：
由于网银系统与后台业务处理系统间通讯异常，造成网银不能确认支付指令结果，则此笔指令为可疑指令；可疑指令将被自动批复，商户、客户可于第二日查询指令状态。
没有收到客户浏览器转发的银行通知：
由于客户浏览器端或互联网通讯等原因可能造成商户端接收不到客户浏览器提交的银行通知。当没有收到银行通知时，可登录工行商户服务网站手工查询指令状态或者商户调用查询接口自动处理。
商户提交的订单信息和银行返回的通知消息都是xml串，并且进行了BASE64编码；
提交和返回的xml都应有xml头；
第 3 章 安全API说明
为了保证商户提交订单数据和银行通知信息数据的完整性，不可抵赖性，现提供一套用于信息签名、验签和BASE64编解码的函数。商户开发时使用这套函数和工行颁发的商户证书进行商户订单信息签名；签名数据项和顺序均固定，具体格式可参见上文的数据定义；同时使用这套API和银行公钥可以验证银行通知消息的有效性。安全API的使用方法可参见相关开发语言的说明和demo程序；
第 4 章 开发步骤
商户程序需在银行模拟测试环境上进行联调后，再投产，以下说明联调开发步骤。
生成订单：
1、商户和当地行联系，申请联调测试；由当地行在模拟测试环境录入商户信息，生成商户证书（pfx格式）；并提供银行模拟测试环境的银行证书公钥文件（用于验证银行签名时使用）；
2、商户或者银行用证书拆分工具将pfx格式的商户证书拆分成扩展名为crt的公钥文件和扩展名为key的私钥文件；（这两个文件用于商户开发API调用来进行商户订单数据签名）
3、商户进行开发，准备要求的订单数据；
4、其中订单签名数据merSignMsg字段是对明文的签名数据；需要使用提供的API函数和商户私钥进行签名，得到签名串，然后做BASE64编码；
5、其中商城证书公钥merCert字段需要使用API函数做BASE64编码；
6、准备好订单数据，即完成订单提交的开发；之后只要将订单提交银行接收入口“https://银行地址/servlet/ICBCINBSEBusinessServlet”，银行来处理B2C指令的资金支付；
接收通知：
交易处理后，会将客户定向回商户网站，此时包含交易结果信息和银行签名。商户接收到银行通知后，需使用开发API和银行公钥来验证银行签名，以确保通知消息的有效性，商户收到接受通知后，可将取货链接返回银行。
以下简要说明验证步骤：
1.获得各字段取值后，注意提交的明文需要进行base64解码才能获得。使用商户开发API和银行公钥文件对表单中的银行签名signMsg进行验签；
2.验签成功后，为确保数据一致，建议商户比较一下通知消息中订单金额、卖家卡号等关键信息和自己记录的是否一致；
3.商户根据交易结果tranStat来更新自己的指令状态和相关数据库信息；
第 5 章 FAQ
1、客户支付成功页面，我希望客户看到取货链接，为什么没有显示取货链接或没有弹出取货页面？
答：
请商户、分行依次做如下检查：
a.请注意此接口采用后台通知方式（同1.0.0.0通知方式），故若显示取货链接，tranData中的notifyType必须配置为HS。取货链接仅当商户收到银行实时通知后返回给银行，详细过程参见第一章的第13点；
b.从外网检查merURL是否能打开（分行人员可将该地址直接输入到浏览器回车看是否能打开此页面）；
c.与分行确认merURL对应的ip地址是否受限（将ip提供给分行后，由分行告知结果），若受限则由分行代为申请放开对此ip的限制；
d.商户端程序不能对银行通知请求做重定向；
e.商户响应银行通知时返回给工行的页面中应包含且只包含形如“http(或https)://www.某B2C商城.com/取货链接.html”的取货链接，不能含有其他内容或html标签。
f.请检查商户响应银行通知时返回给工行的页面是否采用了GBK编码（不论取货链接中是否含有中文字符）。
2、开发接口时，我不了解银行提供的签名方法，或我遇到和签名有关的报错，如何解决？
答：
建议商户首先跑通银行光盘提供的demo用例（分行可能以其他形式提供），结合光盘其他资料和接口文档，即可自行解决大部分疑问。
3、商户的表单提交给工行之后，银行直接显示超时页面（专指含有工行小e人的超时页面）是什么原因？银行直接显示“商户操作非法！”是什么原因？
答：
a.显示超时页面的原因：商户向银行提交的form表单不能含有2.1.1章节中列出的变量以外的其他变量。例如，超时情况通常是商户将“提交按钮”的name属性也传递给了工行，这时只要将“提交按钮”移到form表单以外或将其name属性置空即可。
b.显示操作非法的原因：这种情况通常发生在商户与银行联测阶段，由商户使用本地的静态html文件直接向银行提交form表单导致的。请商户使用商户服务器环境与银行联测即可解决。
4、常见错误代码的自查和解决：
a)接口报错96113375（报文明文格式有误）如何自查？
答：
请将商户程序实际生成的tranData明文，与2.1.3章节的用例明文做仔细对比，确保二者各个节点一一对应，且节点标签大小写、节点顺序也完全一致，详见2.1.1章节。建议使用比较工具进行逐行比较。
b)接口报错96112025（系统日期错误）如何解决？
答：
银行测试环境日期通常不是自然日期且可能会根据需要调整，此时需要与分行联系来取得银行测试环境的日期和时间；商户提交的交易日期时间（orderDate字段）应与银行测试环境保持一致，目前时间差要求控制在十分钟以内。
c)接口报错96113424（订单数据有误）如何解决？
答：
参照2.1.2章节的“客户端IP”一项的说明进行检查。
d)接口报错96113258（商户上送数据有误）如何解决？
答：
参照2.1.2章节的“商户reference”一项的说明进行检查。
5、当仍然有问题解决不了，我需要银行工作人员协助解答时，我应该提供哪些信息？
答：
商户通常应将下列字段邮件发送给给分行（尽可能多的提供下列信息），并等待分行答复。
a.错误代码和错误现象（必须提供准确的错误代码）；
b.所属测试环境（例如模测一套）；
c.章节2.1.1表单定义中的所有字段，主要包括interfaceVersion、tranData、merSignMsg、merCert，请注意应该提供最终提交给银行的表单字段值，无需发源程序；
d.交易日期（自然日期和工行测试环境的日期）；
e.交易时使用的工行卡号；
f.浏览器版本；
g.交易截图。
本文系转载，前往查看
如有侵权，请联系 cloudcommunity@tencent.com 删除。
本文系转载，前往查看
如有侵权，请联系 cloudcommunity@tencent.com 删除。
腾讯云开发者
