网上银行系统C2C信用支付接口商户手册09年版.docx
《网上银行系统C2C信用支付接口商户手册09年版.docx》由会员分享，可在线阅读，更多相关《网上银行系统C2C信用支付接口商户手册09年版.docx（35页珍藏版）》请在冰豆网上搜索。
网上银行系统C2C信用支付接口商户手册09年版
C2C信用支付接口
商户手册
中国工商银行软件开发中心
CopyrightReserved
1.文档属性
文档属性
内容
文档名称：
网上银行系统C2C信用支付接口商户手册
文档版本号：
1.1
文档状态：
正式稿
文档编写完成日期
2007-7-12
2.文档变更历史清单
文档版本号
变更日期
修改人
变更内容简述
1．1
2007-7-12
曾凯
增加描述xml头；
通知消息方式；
1.11
2009-1-21
魏阁麟
修改2.4节“要延长的有效期长度”字段的描述说明
第1章业务说明3
第2章商户接口5
2.1买家预支付6
2.1买家提前支付10
2.1超期商户支付12
2.4商户延期支付到期日13
2.5买家退款申请、撤消、确认、仲裁申请、撤消、确认15
2.6商户单笔订单查询17
2.8通知消息及查询返回18
2.8其他22
第3章商户开发22
第1章业务说明
买家在商户网站进行C2C信用购物交易，工行完成买家、卖家、商户手续费的资金转账。
信用支付的主要作用是，银行建立中间中转账户，买家支付的资金并不直接转付给卖家，而是先转付到银行的中间账户上，此笔从买家账户到银行中间账户的转账称为预支付；预支付后，商户应通知卖家进行发货处理，买家在接收到货物后确认，如果没有问题则在商户发起确认支付，此时将保留在银行中间账户的资金转付到卖家账户和商户手续费账户。
如果买家对于货物存有异议，可以申请部分、全部、当日、隔日的退货处理，当提起申请退货处理后，此时的订单等待卖家进行退货确认，如果卖家允许退货，则在商户发起退货确认，银行将保留在中间账户的资金，部分或者全部的转回买家账户。
如果卖家不同意退货，则可以在商户网站拒绝退货，此时订单资金将恢复为保留状态。
买家仍可提出申请仲裁，此时银行等待仲裁机构对此笔交易的仲裁确认，如果仲裁机构同意退货，则通知银行，银行将保留在中间账户的资金转回买家账户，如果仲裁机构不同意退货，则恢复订单资金的保留状态。
每一笔信用支付的订单设置一个订单有效期。
1、在有效期内，买家可以提出申请退货、申请仲裁处理；提出申请后，需卖家确认，系统会累加卖家确认时间到买家申请时间的时差到订单有效期上，保证买家有足够的控制订单的时长。
卖家不确认，此笔资金也不能转到卖家账户；2、如果卖家发货后，买家收到货物，没有及时进行支付确认，则在订单超过订单有效期后，商户可以发起超期支付请求，此时银行将在中间账户保留的订单资金转付到卖家账户和商户手续费账户。
对于订单有效期，商户有延长的权限，银行提供延长支付到期日接口，商户调用此接口，可以延长原订单提交时设置的到期日，但是不能缩短到期日。
对于买家，如果提出了退货申请、仲裁申请，在卖家没有确认前，有权撤销处理，即撤销退货、撤销仲裁。
撤销之后，订单资金恢复为保留状态，等待买家确认支付，或者由商户超期支付。
业务特色：
如果在预支付接口中，商户上送了买家和卖家的手机号码，本订单在最终的确认支付或者超期支付，即资金成功清算后，会自动向买家、卖家发送短信通知。
为了方便买家处理，在工行的个人网银提供信用支付指令的查询，并提供针对此订单提出退货申请和仲裁申请的功能，如果买家在工行个人网银提起申请，在申请接受后，银行会主动发送商户通知，让商户记录的订单状态与银行同步。
为了方便商户处理，在工行的商户服务页面，提供对于信用支付指令的查询，以及对于申请退款的订单，提供向买家退款功能；对于超期订单，提供向卖家支付功能；当商户员工在工行商户服务页面完成资金处理后，银行会主动发送商户通知，让商户记录的订单状态与银行同步。
由于采用HTTP协议进行商户的通知，HTTP连接的不可靠性造成会有掉单的情况，提供C2C信用支付查询接口，商户可以调用此接口来同步商户和银行之间的订单状态。
允许买家申请部分退货，部分退货可以发起多次，但是退货总额不能超过订单总金额。
商户可以在商户服务页面查询一笔订单对应的多笔退货记录。
资金流向图：
银行端订单状态图：
注：
✓等待银行资金监管、等待银行清算、退款处理中、仲裁处理中，4个状态为银行处理时的中间状态，在这些状态时，不接收商户或买家发起新的申请。
✓对于处于交易失败、清算失败的订单，商户仍可重新提交，最终实现订单的提交和资金清算，如果多次尝试不成功，需检查自身程序和系统运行情况，或者与工行联系。
✓“资金银行监管中”即上文描述的订单资金保留状态。
✓所有银行端的状态变化，会根据此图判断现有状态，是否允许处理，然后到下一个状态。
C2C信用支付交易中，银行提供了多个商户接口，具体内容见下章。
这些接口中只有两个需要买家参与，并且有银行和客户的交互页面，即买家预支付、买家提前支付；这两个交易都是商户形成接口提交数据，然后返回买家的浏览器，这些数据通过买家浏览器POST到银行接收入口，并建立买家到银行的SSL连接，完整买家的交易授权，如买家使用静态支付密码、动态口令卡、U盾证书签名。
其他的接口都是商户直接访问银行网站，没有客户的参与，没有银行页面。
由于此交易状态多，而且能够从商户、银行分别发起交易，从而使订单状态变化，建议商户开发时，判断自身状态，根据规则判断能否修改成下一个状态，此判断在一个事务中完成。
并且对于银行的通知消息，做好短时接收到多笔通知、或者掉单的程序处理。
银行的通知消息会返回银行的时间，商户应根据通知消息中的时间判断银行端此订单的最终状态。
对于最晚通知之前的部分通知可以忽略，只要最终状态和银行一致即可。
商户提交的内容需要按照具体接口说明组织明文数据，注意格式和大小写；并根据要求使用工行安全API和商户API证书进行商户签名。
对于银行返回的通知信息，需要按照接口定义，组织明文，并使用安全API和银行公钥，对银行通知进行验签，保证银行通知的准确，同时建议比较返回的通知的交易数据，与商户数据进行比较，如发现不一致及时分析并与银行联系。
第2章商户接口
个人网银提供C2C信用支付统一的入口地址“https:
//银行地址/servlet/ICBCINBSEBusinessServlet”，系统会根据接口名称和版本进行判断，然后进行处理；注意提交的action地址，预支付、提前支付是通过客户提交，提交的地址是“/servlet/ICBCINBSCreditCustServlet”，剩下的接口是商户服务器直接提交的，地址是“/servlet/ICBCINBSCreditMerServlet”。
✓买家预支付和提前支付需要和客户进行交互确认，其提交方式是商户订单通过客户浏览器提交银行，建立单向ssl；提交form表单；但是所有交易数据统一为xml格式，将整个xml报作为一个数据项提交，xml使用BASE64编码。
✓除买家预支付和提前支付的其他接口都是商户服务器和银行服务器直接建立单向ssl连接，post方式提交，交易数据使用xml；
✓商户通知：
1、商户服务器和银行服务器直接建立单向ssl连接的交易，银行处理后，在原连接中返回商户通知；2、对于客户post到银行，以及客户直接在银行的操作，商户在商户服务页面的操作，需要银行主动发送变更通知给商户，此时使用http连接方式，post方式提交，交易数据使用xml；
✓银行的主动通知和商户直接和银行交互后的返回，采用统一的数据格式返回，即下面的“通知消息及查询返回接口”。
即通常情况下各接口的请求，银行都是返回相同的通知格式，其中的各字段如果有值则返回，如果没有值则为空或初始值；
✓传输数据的编码方式是GBK，XML格式串需要XML头，即
xmlversion="1.0"encoding="GBK"standalone="no"?
>
✓对于需要和客户交易的两个交易，定制错误页面，在其上增加返回商户的链接，当点击时，网银后台发送通知，同时返回客户端，通过客户端再重定向到商户，其中含通知消息。
如果准备通知消息数据时程序异常，后台将不发送通知，前台也返回商户时也不含通知消息。
✓接口版本号是全部接口的统一的版本号，不是某一个接口自己的属性；使用1.0.0.0接口提交的处理，返回就使用1.0.0.0的通知消息格式。
✓商户订单的标识：
商户号、订单号、商户提交日期（注意：
没有商户提交时间）要求商户在其自身系统一天内的订单号不能重复。
对于预支付失败的指令，允许重新提交，此时订单标识不能变，即商户号、订单号、商户提交日期三项不变，但是商户提交时间可以变，而且总的提交时间在银行前后三小时范围内。
所有接口都是使用form表单的方式进行提交，表单包含3个数据项【interfaceName信用支付接口名称】、【interfaceVersion信用支付接口版本】、【CREDIT_PAY_DATA信用支付交易数据】；
样例：
//银行地址/servlet/ICBCINBSCreditCustServlet">
注：
CREDIT_PAY_DATA的值需base64编码。
Action地址根据不同接口不同。
2.1买家预支付
Xml格式字段说明：
变量名称
变量命名
长度定义（以字节为单位）
说明
接口名称
interfaceName
=23
必输，
取值：
“ICBC_PERBANK_CREDIT_PAY”
接口版本号
interfaceVersion
=7
必输，
取值：
“1.0.0.0”
订单号
orderID
MAX（30）
必输，
客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。
工行通过订单号加订单日期时间来唯一确认一笔订单的重复性。
商户代码
merID
MAX（20）
必输，
唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。
订单日期时间
merOrderTime
=14
必输，
格式为：
YYYYMMDDHHmmss
要求在银行系统当前时间的前3小时和后3小时范围内，否则判定交易时间非法。
其他商户接口中都需要上送此时间
检验联名标志
verifyJoinFlag
=1
必输，
取值“1”：
客户支付时，网银判断该客户是否与商户联名，是则按上送金额扣帐，否则展现未联名错误；
取值“0”：
不检验客户是否与商户联名，按上送金额扣帐。
卖家卡号/账号
sellerAcct
MAX（19）
必输，
支持账户和卡号
卖家姓名
sellerName
MAX（60）
必输，
注意是60字节
商户手续费入账账号
merAcctNum
MAX（19）
必输，
手续费入账账户户名
merAcctName
MAX（19）
必输，
订单金额
amount
MAX（10）
必输，
客户支付订单的总金额，一笔订单一个，以分为单位。
不可以为零，必需符合金额标准。
币种
currType
MAX（3）
默认人民币“001”
有效期长度
orderPeriod
MAX（4）
由于商户和银行存在时间差，要求商户提交有效期长度，银行根据自己时间计算到期日
单位小时
最小值：
24小时
最大值：
360小时，即15天
已含运费金额
carriageAmt
MAX（18）
选输
以分为单位
商品名称
goodsName
MAX（60）
选输
单位字节
商品编号
goodsNo
MAX（30）
选输
单位字节
商品数量
goodsNum
MAX（10）
选输
单位字节
商户提示
merHint
MAX（120）
选输
单位字节
买家手机号码
buyerPhoneNum
11
选输
支持移动、联通手机接收交易成功通知
卖家手机号码
sellerPhoneNum
11
选输
支持移动、联通手机接收交易成功通知
接收支付结果信息通知程序地址
merURL
MAX（200）
必输，
使用HS通知类型的商户用来接收工行订单支付结果的URL；银行使用HTTP协议POST方式向此地址发送通知信息；目前只支持80端口。
使用“AG”通知类型的商户,该字段可以为空或者不上送该字段；但在签名数据中必须包含此项，取值可为空。
取值举例：
（注意需要写上“http:
//”）
返回商户地址
backMerURL
必输，
交易结束返回商户URL，完成闭环
返回商户数据
backMerData
必输，
交易结束返回商户URL时，post的保留数据（可用做维护原有商户端session）
订单签名数据
merSignMsg
无限制
必输，
商户使用工行提供的签名API接口和商户证书将交易数据按一定格式进行然后进行BASE64编码后得到的字符串。
（格式单独说明）
商户证书公钥
merCert
无限制
必输，
商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串。
商户接收银行通知地址为必输项，且银行保存，用于后续的银行端变更指令状态（如银行端申请仲裁、撤销仲裁、退货确认、超期付款交易）时进行通知；也用于买家预支付和提前支付；
返回商户地址为必输项，买家预支付和提前支付除后台发送通知外，在结果页面，将客户重定向到商户时，仍然向商户提交结果信息。
对于有页面交互的（类似于B2C的）交易，主要使用通过客户端浏览器重定向到商户的方式，返回交易结果信息，将后台通知作为辅助手段，以后可能取消后台的发送。
Xml格式说明：
（即将此xml进行base64编码作为CREDIT_PAY_DATA的值）
格式一定，允许空值；注意整个字符串中不要有空格、tab、回车换行等控制字符，要作为字符串提交。
（下面的接口也都是这样）
xmlversion="1.0"encoding="GBK"standalone="no"?
>
订单签名数据merSignMsg的格式：
按照如下格式，组织签名的明文数据，都是key=value的形式，然后使用&符号连接；
没有取值的变量就留空，但不能是null；（下面的接口也都是这样）
interfaceName=&interfaceVersion=&orderID=&amount=&currType=&merOrderTime=&orderPeriod=&sellerAcct=&sellerName=&merID=&merAcctNum=&merAcctName=&verifyJoinFlag=&buyerPhoneNum=&sellerPhoneNum=&merURL=&backMerURL=&backMerData=
2.1买家提前支付
使用form方式提交，提交数据名称是CREDIT_PAY_DATA=XXXX
XXXX表示BASE64编码的xml格式的字符串
变量名称
变量命名
长度定义（以字节为单位）
说明
接口名称
interfaceName
=29
必输，
取值：
“ICBC_PERBANK_CREDIT_AHEAD_PAY”
接口版本号
interfaceVersion
=7
必输，
取值：
“1.0.0.0”
订单号
orderID
MAX（30）
必输，
客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。
工行通过订单号加订单日期来唯一确认一笔订单的重复性。
商户代码
merID
MAX（20）
必输，
唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。
订单日期时间
merOrderTime
=14
必输，
格式为：
YYYYMMDDHHmmss
原提交订单时上送的时间
交易日期时间
merTranTime
=14
必输，
格式为：
YYYYMMDDHHmmss
要求在银行系统当前时间的前3小时和后3小时范围内，否则判定交易时间非法。
商户提示
merHint
MAX（120）
选输
商户收费金额
feeAmt
MAX（10）
必输，
可为零，以分为单位，必需符合金额标准。
返回商户地址
backMerURL
必输，
交易结束返回商户URL，完成闭环
返回商户数据
backMerData
必输，
交易结束返回商户URL时，post的保留数据（可用做维护原有商户端session）
订单签名数据
merSignMsg
无限制
必输，
商户使用工行提供的签名API接口和商户证书将交易数据按一定格式进行然后进行BASE64编码后得到的字符串。
（格式单独说明）
商户证书公钥
merCert
无限制
必输，
商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串。
xmlversion="1.0"encoding="GBK"standalone="no"?
>
订单签名数据merSignMsg的格式：
interfaceName=&interfaceVersion=&orderID=&merOrderTime=&merTranTime=&feeAmt=&merID=&backMerURL=&backMerData=
2.1超期商户支付
变量名称
变量命名
长度定义（以字节为单位）
说明
接口名称
interfaceName
=31
必输，
取值：
ICBC_PERBANK_CREDIT_OVERDUE_PAY
接口版本号
interfaceVersion
=7
必输，
取值：
“1.0.0.0”
订单号
orderID
MAX（30）
必输，
客户支付后商户网站产生的一个唯一的定单号，该订单号应该在相当长的时间内不重复。
工行通过订单号加订单日期来唯一确认一笔订单的重复性。
商户代码
merID
MAX（20）
必输，
唯一确定一个商户的代码，由商户在工行开户时，由工行告知商户。
订单日期时间
merOrderTime
=14
必输，
格式为：
YYYYMMDDHHmmss
原提交订单时上送的时间
交易日期时间
merTranTime
=14
必输，
格式为：
YYYYMMDDHHmmss
要求在银行系统当前时间的前3小时和后3小时范围内，否则判定交易时间非法。
商户收费金额
feeAmt
MAX（10）
必输，
可为零，以分为单位，必需符合金额标准。
订单签名数据
merSignMsg
无限制
必输，
商户使用工行提供的签名API接口和商户证书将交易数据按一定格式进行然后进行BASE64编码后得到的字符串。
（格式单独说明）
商户证书公钥
merCert
无限制
必输，
商户用二进制方式读取证书公钥文件后，进行BASE64编码后产生的字符串。
xmlversion="1.0"encoding="GBK"standalone="no"?
>
升级会员 