招商银行网上支付商户手册

招商银行网上支付商户手册 招商银行网上支付商户手册 修订日期：2005年8月1日 目录 2手册说明 21．本手册的读者范围 22．前提条件和相关信息 23．相对以前版本的更新 2一．招商银行网上支付简介 21．什么是招商银行网上支付 22．如何成为招商银行网上支付特约商户 33．如何使用招商银行网上支付系统 34．加入招商银行网上支付，对商户电脑系统有什么要求 35．如何与招商银行联系 36．招商银行网上支付的安全措施 4二．系统管理 41．实体关系 52．系统管理 6三．支付交易 61．连接方式1 72．连接方式2 103．连接方式3 12四．人工定单管理 121．操作员登录 122．结帐 123．部分结帐 124．撤销 135．自动撤消 136．退款 13五．程序定单管理 131．程序定单管理简介 132．商户开发指引 142．1．采用支付方式1的商户 142．2．采用支付方式2、3的商户 152．3．分页方式查询的使用方法 152．4．交易管理开发包使用注意事项和建议 15六．旧商户系统用户须知 16附录：开发包接口参考 161. DLL版本的开发包 161. 1. 使用Lib形式的商户开发包 161．2. 使用Dll形式的商户开发包 161．3. DLL的其他使用形式 161．4． 开发包中的API说明： 212. 控件版本的交易管理开发包 212．1．注册控件 212．2．开发包中的API说明 243. Java版本的交易管理开发包 241. 使用Java版商户开发包前的准备工作 252．检验数字签名API说明 262．定单管理API说明 手册说明 1．本手册的读者范围 本手册适用于希望成为招商银行网上支付商户，或者已经成为招商银行网上支付商户的业务管理人员、电脑系统开发人员。 2．前提条件和相关信息 前提条件是对Internet、电脑有初步的了解，对一些常见的技术名词有一定的认识。 3．相对以前版本的更新 相对以前版本，本文更新了商户内部管理模式，增加了新的管理功能，增强了连接方式。 一．招商银行网上支付简介 1．什么是招商银行网上支付 招商银行网上支付是招商银行提供的网上付款结算平台，通过这个平台，数千万招商银行持卡人可以向特约商户进行网上付款，全国联网，实时到帐。 2．如何成为招商银行网上支付特约商户 （1） 商户与当地招商银行的分行个人银行部联系，申请成为我行的网上特约商户，填写相关资料。联系方式及联系人，请查阅招商银行网站（http://www.cmbchina.com）。 （2） 办理签定合约手续。 （3） 商户在我行开立结算帐户。结算帐户设立浮动备付金，备付金比例按照商户资信情况确定。 （4） 根据银行提供的技术接口，商户联通与我行的支付网络。 3．如何使用招商银行网上支付系统 （5） 付款通道。付款通道是持卡人进行网上付款的界面，商户系统以Internet超链接的方式，从商户网站转到银行的付款通道，对商户电脑系统没有特殊要求。 （6） 商户管理。商户可以通过以下几种方式管理招商银行的定单： [1] 商户业务管理网站：Web界面，人工管理定单，为特约商户提供全面 的网上支付业务管理功能。 [2] 定单下载工具：方便特约商户下载自己的定单数据，进行进一步处理。 [3] 支付软件开发包：提供二次开发接口，在商户系统中嵌入支付管理功 能，自动、实时管理定单。 4．加入招商银行网上支付，对商户电脑系统有什么要求 招商银行提高多种方式供商户使用，商户可根据自己的情况选择。 最简单的方式，商户以网页中的Internet超链接转到银行的付款通道，以商户业务管理网站管理定单。在这种情况下，商户甚至可以没有自己的电脑系统。 如果商户不具备程序开发能力，但有常见的办公处理软件使用经验，可以通过定单下载工具下载数据，结合商户业务管理网站，自己在办公处理软件中处理。 如果商户开发能力较强，可以通过银行提供的软件开发包开发软件，把自己的系统和银行对接，就可以全自动、实时地处理业务。 5．如何与招商银行联系 请到招商银行网站（http://www.cmbchina.com）查阅。 6．招商银行网上支付的安全措施 基本的网上交易的传输安全控制手段采用SSL(Secure Socket Layer)，SSL是一种被广泛使用的INTERNET传输加密。银行端的WEB SERVER将安装一个证书(Certificate)，客户端的浏览器发送CGI请求时使用https。所有用https发送的请求以及Web Server返回的结果都会自动使用SSL加密。 对商户来说，商户在其管理电脑上登录时，要提供登录密码。为了增加商户登录的安全性, 在登录页之前增加了一个预登录页, 商户需先输入预登录密码才能进入到登录页，预登录密码固定为“75268”，不能修改。 每个商户可以设置多个操作员，每个操作员拥有不同的密码，其权限以岗位的方式组织，每个岗位有不同的权限，以实现企业内部的安全管理。对风险较高的操作，如退款，还要求配合企业证书IC卡操作。 二．系统管理 1．实体关系 商户的系统管理包括以下内容： （1） 店铺 店铺是生成定单的基础实体，每个商户至少有一个由银行自动生成的店铺，也可以由商户自行设置多个店铺，以便区分不同的交易，以及不同的定单管理，等等。 注意，这里的店铺并非某些支付平台网站上的“店铺”概念，这里的“店铺”纯粹是为了商户分权限管理定单，例如为冲值类型支付分配一个“店铺”，为购物类型支付分配另一个“店铺”，等等，数目不会很大，否则商户内部管理这些权限将是非常烦琐的。而支付平台网站上“店铺”，可能是某个公司，甚至某个人在支付平台上注册的基本单位，其数目是相当庞大的。 （2） 定单 每笔交易视为一个定单，由商户生成定单号，以后可对该定单进行后续处理，如结帐（包括结帐、部分结帐、撤消）、退款、查询等。 （3） 岗位 岗位实际上是权限的组合，可以精细到对不同店铺生成的定单进行不同的操作权限，例如A岗位能对0001店铺定单查询，B岗位能对0001、0002店铺定单结帐、退款，等等。每个岗位可以管理多个店铺，每个店铺也可以由多个岗位管理。 （4） 操作员 操作员是商户管理定单的直接操作者，每个操作员有一个4位数字的操作员号，每个操作员必须赋予至少一个岗位，也可以赋予多个岗位，以适应企业内部灵活的管理方式。操作员的权限由其岗位决定。 （5） 系统管理员 系统管理员可以对店铺、岗位、操作员等进行增加、修改、删除等操作。 以上实体的关系可用下图说明： 2．系统管理 系统管理指商户系统管理员对店铺、岗位、操作员等进行增加、修改、删除等操作。通过系统管理，商户可以灵活配置自己的业务模式，适应自己的业务需求。 （1） 系统管理员登录 每个商户有一个系统管理员，商户开通招商银行网上支付后，银行自动生成一个系统管理员。系统管理员登录需要选择开户分行，输入商户号和管理员密码。 （2） 店铺管理 系统管理员可以增加、修改、删除店铺。一般来说，一个商户只需一个店铺即可，但如果需要对定单区别处理，可以增加新店铺。例如跨地区的商户需要把北京、上海的定单分开处理；再如需要分配不同的操作员管理不同类型的定单，等等。但是，店铺不宜太多，一般不要超过5个，否则商户内部的管理、权限的分配调整等等将比较烦琐。 （3） 岗位管理 系统管理员可以增加、修改、删除岗位。岗位实际上是权限的组合，因此岗位不宜太多，否则商户内部的管理、权限的分配调整等等将比较烦琐。 （4） 操作员管理 系统管理员可以增加、修改、删除操作员。每个操作员必须赋予至少一个岗位，也可以赋予多个岗位。 三．支付交易 1．连接方式1 在网上交易过程中，用户先在商户网页中选择商品。当用户在支付网页中选择招商银行网上支付付款时，商户支付网页向银行WEB系统发出支付命令(见图一)。银行WEB系统处理完支付请求后，将回送用户支付结果页面。 连接方式1 支付命令格式如下： https://netpay.cmbchina.com/netpayment/BaseHttp.dll?PrePayC?BranchID=xxxx& CoNo=xxxxxx&BillNo=xxxxxx&Amount=xxx.xx&Date=YYYYMMDD 参数说明： BranchID: 商户开户分行号，请咨询开户的招商银行分支机构； CoNo: 商户号，6位数字，由银行在商户开户时确定； BillNo: 定单号，6位或10位数字，由商户系统生成，一天内不能重复； Amount: 定单总金额，格式为：xxxx.xx元； Date: 交易日期，格式：YYYYMMDD。 支付页面提交的FORM格式示例如下：

定单号	000023
金 额	818.66
日 期	20050101

连接方式1的特点是商户WEB系统通过支付页面把控制引导到银行WEB系统，银行WEB系统处理完支付请求后回送支付结果页面给用户，控制没有再回到商户WEB系统。 商户在银行网站进行定单管理时可以知道定单的付款情况。如果商户系统需要立刻核实定单付款情况，可以使用一个银行提供的开发包中的定单状态查询接口向银行WEB系统查询某个定单的状态。有关直联定单状态查询接口请见附录。 2．连接方式2 某些商户在用户完成支付过程后希望控制能够从银行WEB系统自动转回商户WEB系统，并且商户WEB系统能够知道用户的付款情况。比如，出售信息产品的商户，在支付成功的情况下，商户的结果页除包含支付成功通知信息外，还可以包含用户购买的信息产品。 为了解决这个问，要求商户WEB系统必须提供一个支付结果通知命令。银行WEB系统在收到支付网页发出的支付命令后，先执行扣款操作，然后调用商户WEB系统的支付结果通知命令，把支付结果通知商户WEB系统，同时取得商户WEB系统生成的支付结果页面(由支付结果通知命令生成)。最后，银行WEB系统把由商户WEB系统的支付结果通知命令生成的支付结果页返回用户的浏览器。这就是连接方式2(见下图)。 连接方式2 支付结果通知命令格式型如： http://www.merchant.com/path/ProcResult.dll?Succeed=..&BillNo=..&Amount=..&Date=..&Msg=..&signature=.. 其中，path和ProcResult.dll由商户任意确定，并且支付命令中可包含多个path，即可有path1/path2/path3。 参数说明： Succeed： 取值Y(成功)或N(失败)； BillNo: 定单号(由支付命令送来)； Amount: 实际支付金额(由支付命令送来)； Date: 交易日期(主机交易日期)； Msg: 银行通知用户的支付结果消息。信息的前38个字符格式为：4位分行号＋6位商户号＋8位银行接受交易的日期＋20位银行流水号；可以利用交易日期＋银行流水号对该定单进行结帐处理； Signature: 银行用自己的Private Key对通知命令的签名。 注意: (1) 商户系统如果对银行通知命令的真实性有较高要求，必须用银行提供的开发包中的函数，结合银行的Public Key（可从网上下载或向银行索取）验证。具体用法请参考附录。 (2) 在Succeed为Y时，商户在支付结果通知命令中必须判断Amount的值，该值为用户的实际支付金额，以此金额为准。不能以之前系统产生定单时的金额为准！这是为了防止用户在得到支付页面后修改支付金额。 (3) 银行返回的交易日期是银行主机的交易日期，对于每天重复使用定单号的商户，可能会在0点左右与商户日期有1天的差别，按日期+定单号对帐时，可能和商户自己的定单记录有冲突。如果生成定单号永远不重复，则可以按定单号和商户自己的定单记录对帐，无须核对日期，因此不会有冲突问题，但是，永远不重复的6位定单号，部分商户可能不够用，建议这些商户使用10位的定单号。 (4) 在正式交易中不要使用000000的定单号，因为测试接口在发通知时，定单号固定为000000。 (5) 注意：商户URL中，不能带有端口号。只能采用标准HTTP或者HTTPS方式。 连接方式2的支付命令格式有别于连接方式1，其格式为： https://netpay.cmbchina.comt/netpayment/BaseHttp.dll?PrePayC1? BranchID=xxxx& CoNo=..&BillNo=..& Amount=..&Date=..&MerchantUrl=.. 前五个参数同连接方式1，第六个参数MerchantUrl为支付结果通知命令中参数部分之前的部分，也就是http://www.merchant.com/path/ProcResult.dll。注意：MerchantUrl不能带商户参数。 在方式2中，若用户付款后银行WEB系统或者商户WEB系统出现故障，则可能出现用户已付款但是商户WEB系统不知道的情况，或者出现用户已付款但是用户浏览器未接收到结果页的情况。这类情况属于正常情况，商户可以主动从银行系统查询该定单的真正状况。商户系统应当考虑相应的解决办法，而不能依赖于这个通知到达与否，决定是否给消费者提供商品或服务。 和方式1比较，方式2在用户完成支付操作后控制又回到商户的系统(用户处于商户WEB系统生成的支付结果页中)，增加了银行WEB系统调用商户WEB系统的支付结果通知命令的过程。方式2比方式1复杂，并且商户WEB系统必须处理异常情况。但是方式2功能较强，使支付过程变得平滑无缝。 在商户的Web系统向银行返回结果网页时，网页中应当有，供银行判断是否为有效返回网页，以避免商户服务器失控后自动返回未知的信息而使消费者迷惑。不管是商户停机、网络中断或者Web服务器失控，银行都将屏蔽商户系统的问题，并用正常的网页替代商户网页返回给消费者，使消费者能继续正确操作。 考虑到方式2比较复杂，并且需要连接商户端程序，我们提供了测试接口以方便商户开发程序时测试。使用该测试接口模拟真实的数据，但无须真实的商户代码和付款卡号，银行系统也不记录交易数据（商户不能查询或结帐使用该测试接口产生的交易数据）。测试接口的使用方法和真实接口一致，只需由真实接口的PrePayC1改为测试接口的TestPrepayC1。即 https://netpay.cmbchina.com/netpayment/BaseHttp.dll?PrePayC1? BranchID=xxxx& CoNo=..&BillNo=..& Amount=..&Date=..&MerchantUrl=.. 改为 https://netpay.cmbchina.com/netpayment/BaseHttp.dll?TestPrePayC1? BranchID=xxxx&CoNo=..&BillNo=..& Amount=..&Date=..&MerchantUrl=..。 注意：为防止用户利用测试接口扰乱商户正式运行的服务器，银行的测试接口通知信息中，BillNo始终为“000000”。 建议： 在本方式中，虽然在消费者付款成功后向商户发通知，但由于Internet线路问题、商户网络配置改变问题、商户服务器问题、商户程序问题等原因，商户最终接收银行通知的程序可能收不到银行通知，因此，商户不能仅仅凭是否收到银行通知确定是否给消费者提供服务，在商户作系统时也应当考虑到这个因素。另外，接收通知的程序应当能处理重复通知的情况。 3．连接方式3 某些商户在使用连接方式2后，还需要在银行的支付结果通知命令中带上商户自己的参数，比如商户希望知道是哪个分支机构的定单，定单在商户内部处理的不同于定单号的流水号，或者商户希望借助这个参数建立完整的session，等等。 为了解决这个问题，在连接方式2的基础上，招商银行提供带商户参数的连接方式。这就是连接方式3。 图三、连接方式3 由图示可知，方式3的流程与方式2完全一样，只是在命令格式上增加了商户参数。 连接方式3的支付命令格式有别于连接方式2，其格式为： https://netpay.cmbchina.com/netpayment/BaseHttp.dll?PrePayC2? BranchID=xxxx& CoNo=..&BillNo=..& Amount=..&Date=..&MerchantUrl=..&MerchantPara=.. 参数说明： BranchID: 商户开户分行号，请咨询开户的招商银行分支机构； CoNo: 商户号，6位数字，由银行在商户开户时确定； BillNo: 定单号，6位或10位数字，由商户系统生成，一天内不能重复； Amount: 定单总金额，格式为：xxxx.xx元； Date: 交易日期，格式：YYYYMMDD。 MerchantUrl 支付结果通知命令中参数部分之前的部分，例如 http://www.merchant.com/cgi_bin/function.asp。 注意：MerchantUrl自身不能带商户参数。 MerchantPara 商户需要银行在支付结果通知中转发的商户参数。 支付结果通知命令格式型如： http://www.merchant.com/path/ProcResult.dll?Succeed=..&CoNo=..&=BillNo=..& Amount=..&Date=...&MerchantPara=...&Msg=..&signature=.. 参数说明： Succeed： 取值Y(成功)或N(失败)； CoNo: 商户号，6位长数字，由银行在商户开户时确定； BillNo: 定单号(由支付命令送来)； Amount: 实际支付金额(由支付命令送来)； Date: 交易日期(由支付命令送来)； Msg: 银行通知用户的支付结果消息。信息的前38个字符格式为：4位分行号＋6位商户号＋8位银行接受交易的日期＋20位银行流水号；可以利用交易日期＋银行流水号＋定单号对该定单进行结帐处理； MerchantPara：商户自己的参数； Signature: 银行用自己的Private Key对通知命令的签名。 注意: (1) 商户系统如果对银行通知命令的真实性有较高要求，必须用银行提供的开发包中的函数，结合银行的Public Key（可从网上下载或向银行索取）验证。具体用法请参考附录。 (2) 在Succeed为Y时，商户在支付结果通知命令中必须判断Amount的值，该值为用户的实际支付金额，以此金额为准。不能以之前系统产生定单时的金额为准！这是为了防止用户在得到支付页面后修改支付金额。 (3) 商户如果需要不止一个参数，可以自行把参数组合、拼装，但组合后的结果不能带有’&’字符（如果带有’&’字符，银行收到这样的支付请求时将认为其后是另一个参数，其他可能被浏览器转义的特殊字符也应当避免），总长不能超过128个字节。例如，商户需要银行通知中转发 ReferenceNo=12345678&Branch=上海&SessionID=20010901， 则可以在PrePayC2中写成 MerchantPara=ReferenceNo=12345678|Branch=上海|SessionID=20010901 (4) 银行返回的交易日期是银行主机的交易日期，对于每天重复使用定单号的商户，可能会在0点左右与商户日期有1天的差别，按日期+定单号对帐时，可能和商户自己的定单记录有冲突。如果生成定单号永远不重复，则可以按定单号和商户自己的定单记录对帐，无须核对日期，因此不会有冲突问题，但是，永远不重复的6位定单号，部分商户可能不够用，建议这些商户使用10位的定单号。 (5) 在正式交易中不要使用000000的定单号，因为测试接口在发通知时，定单号固定为000000。 (6) 注意：商户URL中，不能带有端口号。只能采用标准HTTP或者HTTPS方式。 在方式2中，若用户付款后银行WEB系统或者商户WEB系统出现故障，则可能出现用户已付款但是商户WEB系统不知道的情况，或者出现用户已付款但是用户浏览器未接收到结果页的情况。这类情况属于正常情况，商户可以主动从银行系统查询该定单的真正状况。商户系统应当考虑相应的解决办法，而不能依赖于这个通知到达与否，决定是否给消费者提供商品或服务。 和方式1比较，方式3在用户完成支付操作后控制又回到商户的系统(用户处于商户WEB系统生成的支付结果页中)，增加了银行WEB系统调用商户WEB系统的支付结果通知命令的过程。方式3比方式1复杂，并且商户WEB系统必须处理异常情况。但是方式3功能较强，使支付过程变得平滑无缝。 考虑到方式3比较复杂，并且需要连接商户端程序，我们提供了测试接口以方便商户开发程序时测试。使用该测试接口模拟真实的数据流程，但无须真实的商户代码和支付卡号，银行系统也不记录交易数据（商户不能查询或结帐使用该测试接口产生的交易数据）。测试接口的使用方法和真实接口一致，只需由真实接口的PrePayC2改为测试接口的TestPrepayC2。即由 https://netpay.cmbchina.com/netpayment/BaseHttp.dll?PrePayC2? BranchID=xxxx& CoNo=..&BillNo=..& Amount=..&Date=..&MerchantUrl=..&MerchantPara=.. 改为 https://netpay.cmbchina.com/netpayment/BaseHttp.dll?TestPrePayC2? BranchID=xxxx& CoNo=..&BillNo=..& Amount=..&Date=..&MerchantUrl=..&MerchantPara=。 注意：为防止用户利用测试接口扰乱商户正式运行的服务器，银行的测试接口通知信息中，BillNo始终为“000000”。 建议： 虽然在消费者付款成功后向商户发通知，但由于Internet线路问题、商户网络配置改变问题、商户服务器问题、商户程序问题等原因，商户最终接收银行通知的程序可能收不到银行通知，因此，商户不能仅仅凭是否收到银行通知确定是否给消费者提供服务，在商户作系统设计时也应当考虑到这个因素。商户系统必须能处理重复通知的情况。 四．人工定单管理 1．操作员登录 为方便商户业务的管理，商户有必要创建不同的的操作员并对其进行权限分配。操作员创建后，就可以以定单操作员的身份登录商户系统，在其权限范围内进行查询、结账、部分结账、撤销、退款等不同的操作，完成定单管理工作。 2．结帐 对冻结结账的商户，需要商户自己手动处理定单的结账操作。以定单操作员登录，先选择要结账的未结账定单，再进行提交。 3．部分结帐 以定单操作员登录，先选择要部分结账的未结账定单，输入部分结账金额，再进行提交。 4．撤销 以定单操作员登录，先选择要撤销的未结账定单，再进行提交。 5．自动撤消 对冻结结账的商户，若定单在招商银行预定的时间之内没有被处理，系统将对其自动撤销。 6．退款 使用前，商户需要联系招商银行开通退款功能。 退款时需要验证操作者身份，如企业证书卡、密码等信息，退款时按照界面提示进行操作。 五．程序定单管理 1．程序定单管理简介 如果商户每日定单数量不多，完全可以通过我行提供的网上商户系统进行查询和结帐处理，则可以跳过本节。 对于那些网上支付交易较为频繁的商户，每天的交易笔数很多。如果采用手工结帐、对帐处理，工作量大，繁琐而且还容易出错。 招商银行网上支付系统提供了“程序结帐”功能，可以实现商户的查询对帐、结帐过程全自动化，可以完全不需要人工参与，还能够实现商户系统和银行系统数据整合。 招商银行网上支付系统的“程序定单管理”功能，是通过“网上支付系统定单管理开发包”（简称商户开发包）来实现的。通过这个开发包，商户可以通过程序自动完成以下工作： · 查询未结帐定单 · 查询已结帐定单 · 对未结帐定单进行处理（结帐、部分结帐或者撤销） 此外，交易管理开发包中也提供了一个“对银行签名验证的功能”。该功能与程序定单管理无关。后面有对该功能专门的说明（参见附录）。 “招商银行网上支付系统定单管理开发包”有DLL版本、控件版本和Java版本。不同的版本功能上是完全相同的。商户可以根据自己的情况，选择合适的交易管理开发包版本。 2．商户开发指引 首先，应该根据自己的情况，选择一个合适版本的开发包。目前招商银行网上支付交易管理开发包有3个版本：DLL版本、控件版本和Java版本。 这里给出开发包一般使用方法，具体每个版本的使用方法，请参考附录。 我们分两种商户：采用支付方式1的商户，和采用支付方式2、3的商户。下面分别说明商户通常使用的系统结构，和如何使用开发包实现和银行系统对接。 2．1．采用支付方式1的商户 首先商户有自己的定单系统，能够产生和记录每一笔网上支付的定单信息。商户通常有一个定期运行的自动结帐程序。自动结帐程序定期的向银行查询所有的支付成功的定单，然后根据查询结果，更新商户自己的定单信息。 这类商户的自动结帐程序，处理过程是这样的： 1. 调用登录接口，登录 2. 调用“查询未结帐定单”功能，查询未结帐定单，然后将这些定单和商户自己的定单系统中的数据进行对比。 3. 根据对比结果，更新商户自己定单系统中，相应定单的状态，并分别调用开发包中的结帐、部分结帐和撤销功能，对这些定单进行结帐、部分结帐或者撤销处理。 4. 调用退出接口，退出 以上步骤定时进行（比如一天一次，或者半小时一次） 2．2．采用支付方式2、3的商户 对于支付支付方式2和支付方式3的商户，由于商户能够及时收到支付成功的通知，故商户的定单系统中基本都记录了已经成功完成支付的定单。 这些商户，通常有两个相互独立的程序在使用商户开发包：接受银行通知的程序，和自动对帐/结帐程序。 接受银行通知的程序 1. 收到银行发来的通知命令 2. 调用开发包中验证银行数字签名的API，检查通知内容是否可信 3. 更新商户的定单状态，并登记定单对应的银行流水号、银行处理日期等信息 4. 返回给用户支付成功的信息。 注意： · 接受银行通知的程序应该尽快的返回结果页面，因此处理工作应该尽量少一些。尤其不要在这个过程中登录银行系统进行结帐操作。如果接受通知程序超过规定时间还没有返回结果页面，则银行服务器认为通知失败。 · 接受银行通知的程序，必须能够处理收到重复通知的情况。 自动结帐程序 由于这类商户能收到银行支付成功的通知，因此基本上支付成功的定单在商户的定单系统中都有记录。可以直接对这些定单进行结帐、部分结帐和撤销处理。 由于网络、服务器等各方面的原因，通知并不总是能够到达商户。因此，商户仍然需要一个自动结帐程序，对这部分支付成功但没有通知到的定单进行处理。 1. 先调用开发包中的登录功能登录 2. 先根据商户自己的定单系统中记录的定单，找出要结帐的定单以及相应的流水号（在银行通知参数中有），调用开发包中的结帐或者部分结帐接口，进行结帐处理 3. 调用开发包中的未结帐查询接口，对比商户自己的定单数据，更新商户定单系统的状态，并进行未结帐定单进行处理（结帐、部分结帐或者撤销）。 4. 调用退出功能，退出系统 2．3．分页方式查询的使用方法 为避免一次查询返回很多数据，影响银行交易系统的正常运行，请使用分页查询。 不同版本的开发包，分页查询的处理方法是类似的。分页查询是通过2个辅助API配合具体查询方法来实现查询分页的。 PageReset：第一次调用查询方法之前，先调用一次本方法，表示从第一页开始查询。 HasNextPage：用来检查是否还有数据。 不要同时进行不同的分页查询（比如一边进行分页的未结帐查询过程中，又进行分页的已结帐查询），这样会引起混乱。 2．4．交易管理开发包使用注意事项和建议 · 每个调用都有返回值。商户必须检查返回值，判断所执行的功能是否成功完成。 · 使用分页方式的查询，处理完一页的定单，再查询下一页 · 查询不要过于频繁，不要同时多个登录进行查询。因为查询对于交易系统会造成一定的负担。如果使用不当（例如同时发出多个查询操作，返回大量的定单数据）将影响交易系统的正常运行。如果出现这种情况，银行将关闭商户的程序定单管理功能。 六．旧商户系统用户须知 为了方便商户灵活的管理和配置业务，满足商户当前的潜在需求，招商银行对原有的商户系统进行了改造，旨在为商户提供一个更加灵活和完善的电子商务支付平台；同时，必须兼容原商户系统。 新的商户系统提供了基于店铺、岗位、操作员的灵活的权限定义及分配策略，提供了更易用的定单管理功能。 新的商户系统主要包括商户系统管理、商户定单管理两个子系统，文档前面已有所述。新的商户系统引入了“操作员”的概念，必须输入操作员号、操作员密码等信息才能登录系统进行操作。 对每个商户都会生成1个缺省的店铺（店铺号“0001”，默认情况下，商户生成的定单属于店铺“0001”），1个缺省的系统管理员岗位（岗位号“9999”），1个缺省的具备系统管理员权限的操作员（操作员号“9999”，操作员密码对应原来的商户密码）。商户可以凭以上信息登录进入商户系统管理（在登录类型中选择“系统管理员登录”）进行业务及权限的配置，也可以直接登录进入商户定单管理系统。 一般情况下，商户通过系统管理员来管理店铺、岗位、操作员等资料，通过其他具备不同权限的操作员来管理定单。 原终端商户系统的用户也具备以上特点，除此之外，新的商户系统也会生成操作员来对应每个终端（操作员号对应原来的终端号，操作员密码对应原来的终端密码）。 使用新商户系统的商户，在使用商户开发包时，默认用户为9999（管理员用户），所以登录密码应该用管理员用户9999的登录密码。 附录：开发包接口参考 1. DLL版本的开发包 1. 1. 使用Lib形式的商户开发包 Lib形式的商户开发包实际上只是对DLL开发包的一个输出函数包装，其真正实现部分还是在 DLL中。Lib开发包可以在C/C++程序中按Lib的方式直接加入工程，方便C/C++的开发者。 · 把FirmClient.dll拷贝到系统目录下或者结帐程序自己的目录中，在Windows 95/98/NT/2000中，系统目录位于\system32. · 在C/C++源文件中Include FirmClientAPI.h； · 给C/C++连接器指明FirmClient.lib的位置； · 调用FirmClientAPI.h 中函数； 1．2. 使用Dll形式的商户开发包 · 把FirmClient.dll拷贝到系统目录下或者结帐程序自己的目录中，在Windows 95/98/NT/2000中，系统目录位于\system32。 · 如果商户开发语言是C或C++： . 申明一个HMODULE型变量； . 调用系统函数::LoadLibrary加载FirmClient.dll； . 申明dll中的函数指针； . 调用系统函数::GetProcAddress取得函数指针的值； . 使用函数指针调用dll中相应的函数； . 完成任务后调用系统函数释放FirmClient.dll。 1．3. DLL的其他使用形式 如果商户开发语言不是C或C++,例如 VB,Java,等等，参考相应语言中关于dll调用的说明。 1．4． 开发包中的API说明： （1）基本设置 INET_STATUS SetOptions(char* pszHttpServer, char* pszPort = NULL, char* pszProxyIP = NULL) 使用开发包其他函数之前，必须先调用这个函数进行初始化，设置银行网址及商户的Proxy特性。 参数说明： PszHttpServer 输入参数，银行网址。固定为netpay.cmbchina.com。 PszPort 输入参数，银行Web Server的端口号。如果没有特殊要求，可以忽略该参数或置为NULL PszProxyIP 输入参数，Proxy Server IP地址。如果没有Proxy Server，可以忽略该参数或置为NULL。 返回值 是否成功。如果成功，返回值为0。 返回非0的值表示错误。请调用GetLastErr取得具体的错误信息。 （2）登录 INET_STATUS LoginC(char* pBranchID, char* pszCoNo, char* pszPwd) 进行了基本设置后，应该进行登录。只有成功登录后，才能进行查询、结帐等功能。 参数说明： PbranchID Input.商户开户行代码,4位 PszCoNo Input.商户代码及操作员代码6位或者10位。 6位则为商户号，表示用管理员9999登录。 10位则前面6位为商户号，后面4位为操作员号。 PszPwd Input.商户密码。 返回值 是否成功。如果成功，返回值为0。 返回非0的值表示错误。请调用GetLastErr取得具体的错误信息。 （3）退出 INET_STATUS Logout(); 开发包使用完成后，应调用该函数退出。 （4）定单结帐 INET_STATUS SettleOrder(char* pszCoNo, char* pszBillNo, char* pszRefNo) 参数说明： PszCoNo 输入，商户号 PszBillNo 输入，要处理定单的定单号 PszRefNo 输入，要处理定单的银行流水号。 银行流水号有2个途径获得 · 通过查询未结帐定单的接口获得 · 通过银行支付成功通知，从通知参数中获得 返回值 是否成功。如果成功，返回值为0。 返回非0的值表示错误。请调用GetLastErr取得具体的错误信息。 （5）定单部分结帐 INET_STATUS SettlePartOrder(char* pszCoNo, char* pszBillNo, char* pszRefNo, char* pszPartAmount) 参数说明： PszCoNo 输入，商户号 PszBillNo 输入，要处理定单的定单号 PszRefNo 输入，要处理定单的银行流水号。 银行流水号有2个途径获得 · 通过查询未结帐定单的接口获得 · 通过银行支付成功通知，从通知参数中获得 PszPartAmount 输入，部分结帐金额，不能大于原始定单金额 返回值 是否成功。如果成功，返回值为0。 返回非0的值表示错误。请调用GetLastErr取得具体的错误信息。 （6）定单撤消 INET_STATUS CancelOrder(char* pszCoNo, char* pszBillNo, char* pszRefNo) 参数说明： PszCoNo 输入，商户号 PszBillNo 输入，要处理定单的定单号 PszRefNo 输入，要处理定单的银行流水号。 银行流水号有2个途径获得 · 通过查询未结帐定单的接口获得 · 通过银行支付成功通知，从通知参数中获得 返回值 是否成功。如果成功，返回值为0。 返回非0的值表示错误。请调用GetLastErr取得具体的错误信息。 （7）释放缓冲区内存 INET_STATUS FreeBuffer(char* pBuffer) 每调用一次具体查询方法，如果查询成功，必须调用本方法释放内存。 注意： 1． 每个分页的查询都要释放内存。 2． 如果查询失败，不能释放内存。 参数说明： pBuffer 要释放的缓冲区。该指针必须是由查询未结帐、已结帐定单返回的 返回值 是否成功。如果成功，返回值为0。 返回非0的值表示错误。请调用GetLastErr取得具体的错误信息。 （8）取得错误信息 char* GetLastErr(INET_STATUS isNo); 参数说明： IsNo 输入，最近一次调用接口返回值 返回值 错误的详细信息 取得最近发生的错误信息。 每一个不成功的操作后都应调用该函数及时发现错误原因。 （9）设置分页查询的位置为第一页 void PageReset() 说明：在每次分页查询之前必须调用一次。查询中途如果需要重头查起，也是通过调用PageReset来实现。 （10）判断是否还有更多的数据 int HasNextPage() 功能：在分页查询中，用来判断是否已经查询完了所有数据。 说明：在调用PageReset后，返回FALSE；在调用了分页查询后，如果还有更多的数据，则返回TRUE，否则返回FALSE。 （11）分页查询未结帐定单 INET_STATUS QueryUnsettledOrderByPage(int count,char **result) 参数说明： count 本次查询所返回定单数目。当未结帐定单数目少于给定数目时，返回全部未结帐定单。如果未结帐定单数目比给定数目多，则返回给定数目的定单。下一次调用本函数则从本次的最后一条定单的下一条开始返回。 result 返回的查询结果。格式请看下面说明 如果查询成功，则使用完毕后，请调用FreeBuffer()来释放result占用的内存，否则将导致内存泄漏。 返回值 是否成功。如果成功，返回值为0。 返回非0的值表示错误。请调用GetLastErr取得具体的错误信息。 说明： result 中保存的定单信息由连续的定单记录组成，每个记录包括以下部分： 交易日期--------------"yyyymmdd" 金额--------------------"*****.**" 定单号.-----------------6或10个字符 流水号------------------20 characters 每一部分由字符'\n'分隔。 例如："19980820\n1200.00\n100201\n98082000010700030001\n19980830\n200.00\n100201\n98083000010700030009\n". 以上字符串包括两个定单信息。 （12）分页查询已结帐定单，按交易日查询 INET_STATUS QuerySettledOrderByPage(LPCSTR StartDate, LPCSTR EndDate,int count,char **result) 参数说明： StartDate 查询的起点日期，8位数字 EndDate 查询的终点日期，8位数字 count 本次查询所返回定单数目。当查询结果定单数目少于给定数目时，返回全部定单。如果查询结果定单数目比给定数目多，则返回给定数目的定单。下一次调用本函数则从本次的最后一条定单的下一条开始返回。 result 返回的查询结果。格式请看下面说明 如果查询成功，则使用完毕后，请调用FreeBuffer()来释放result占用的内存，否则将导致内存泄漏。 返回值 是否成功。如果成功，返回值为0。 返回非0的值表示错误。请调用GetLastErr取得具体的错误信息。 说明： result中保存的定单信息由连续的定单记录组成，每个记录包括以下部分： 交易日期--------------"yyyymmdd" 处理日期--------------"yyyymmdd" 金额--------------------"*****.**" 定单号.----------------- 6或10个字符 定单状态---------------1 字符 卡类型------------------2字符 手续费------------------“***.***” 银行受理日期--------“yyyymmdd” 银行受理时间--------“hhmmss” 每一部分由字符'\n'分隔。其中： 定单状态：“0”为已结帐，“1”为已撤销，“2”为部分结帐，“3”为退款记录，5-无效状态，6－未知状态。 卡类型： 02：一卡通 03：信用卡 04：其他行的卡 例如："20130116\n20130116\n0.01\n0000000029\n0\n02\n0.00\n20130116\n141815\n20130115\n20130115\n0.01\n9999990001\n0\n02\n0.00\n20130115\n154257\n ". 以上字符串包括两个定单信息。 （13）分页查询已结帐定单，按结帐日查询（入账明细查询） INET_STATUS QueryTransactByPage(LPCSTR Date,int count,char **result) 参数说明： Date 要查询的结帐日期，8位数字，格式为“YYYYMMDD” count 本次查询所返回定单数目。当查询结果定单数目少于给定数目时，返回全部查询结果。如果查询结果记录数目比给定数目多，则返回给定数目的定单。下一次调用本函数则从本次的最后一条定单的下一条开始返回。 result 返回的查询结果。 如果查询成功，则使用完毕后，请调用FreeBuffer()来释放result占用的内存，否则将导致内存泄漏。 格式为： 交易日期\n处理日期\n金额\n定单号\n订单状态\n卡类型\n手续费\n商户自定义字段\n 其中，订单状态有： 0－已结帐，1－已撤销，2－部分结帐，3－退款，4－未结帐，5-无效状态，6－未知状态 返回值 是否成功。如果成功，返回值为0。 返回非0的值表示错误。请调用GetLastErr取得具体的错误信息。 （14）查询单笔定单 INET_STATUS QuerySingleOrder (char* Date,char* BillNo,char** result) 参数说明： Date 定单交易日期，8位数字，格式为“YYYYMMDD” BillNo 订单号 result 返回的查询结果。 如果查询成功，则使用完毕后，请调用FreeBuffer()来释放result占用的内存，否则将导致内存泄漏。 格式为： 交易日期\n处理日期\n定单状态\n定单金额\n【结帐金额\n】\n卡类型\n手续费\n商户自定义参数\n银行受理日期\n银行受理时间 其中： 定单状态：0－已结帐，1－已撤销，2－部分结帐，3－退款，4－未结帐，5-无效状态，6－未知状态 处理金额仅部分结帐定单才有。因此必须根据定单状态判断是否部分结帐。 返回值 是否成功。如果成功，返回值为0。 返回非0的值表示错误。请调用GetLastErr取得具体的错误信息。 （15）分页查询退款记录 INET_STATUS QueryRefundByDatePage(LPCSTR pstrBeginDate,LPCSTR pstrEndDate,int count,char** result) 参数说明： pstrBeginDate 要查询的开始日期，8位数字，格式为“YYYYMMDD” pstrEndDate 要查询的结束日期，8位数字，格式为“YYYYMMDD” count 本次查询所返回定单数目。当查询结果定单数目少于给定数目时，返回全部查询结果。如果查询结果记录数目比给定数目多，则返回给定数目的定单。下一次调用本函数则从本次的最后一条定单的下一条开始返回。 result 返回的查询结果。 如果查询成功，则使用完毕后，请调用FreeBuffer()来释放result占用的内存，否则将导致内存泄漏。 数据格式为： 退款单流水号\n 商户定单号\n 定单参考号\n 商户定单日期\n 退款币种\n 退款金额\n 费用金额\n 银行受理日期\n 银行受理时间\n 经办操作员号\n 退款日期\n 退款时间\n 退款说明\n … 返回值 是否成功。如果成功，返回值为0。 返回非0的值表示错误。请调用GetLastErr取得具体的错误信息。 （16）检验收到通知内容的真实性（检验数字签名） INET_STATUS CheckInfoFromBank(char* pszPublickeyFilePath, char* pszMsg) 参数说明： pszPublickeyFilePath 输入，银行Publickey文件路径。例如”C:\\PubKey\\CMBPK.key”。 该文件可以在招商银行网上商户登结帐系统的录后的页面界面上下载。 pszMsg 输入，银行发来的通知信息，形如 “Succeed=..&BillNo=..&Amount=..&Date=..&Msg=..&signature=..” 返回值 是否成功。如果成功，返回值为0。 返回非0的值表示错误。请调用GetLastErr取得具体的错误信息。 说明： 和开发包中其他函数不同，调用本函数之前，不需要登录，也不需要进行基本设置。 2. 控件版本的交易管理开发包 2．1．注册控件 使用控件版商户开发包之前，必须先注册商户开发包控件。注册步骤如下 · 把控件版商户开发包的FirmClient.DLL和CMBChina.DLL这2个文件，复制到同一个目录下（建议放到SYSTEM32下面） · 在命令行窗口，把当前工作目录转到控件版商户开发包所在的目录 · 执行命令regsvr32 CMBChina.dll 注意： 1、在某些运行环境中，控件所能够使用的内存会收到限制（例如运行在ASP脚本中）。如果在这种环境中，如果一次查询返回大量