农行网上支付平台-交易市场接口编程指南-PHP_Edition-V10.docx

中国农业银行网上支付平台交易市场 PHP商户接口编程指南Java EditionV1.0修订历史纪录日期版本说明作者2009/11/18V1.0初稿童益柱目录1.简介31.1目的31.2功能描述31.3总体架构图32.接口开发软件包说明43.安装步骤53.1安装前检查53.2系统配置53.3Web Services接口应用配置53.4配置测试应用64.配置文件说明75.范例交易说明85.1交易流程85.1.1Web Services技术的引入85.1.2签约和解约交易85.2交易开发说明105.2.1开发环境的配置105.2.2编写web services接口函数105.2.3编写php接口191. 简介1.1 目的提供商户端交易网站通过中国农业银行网上支付平台提供的商户端开发软件包实现功能的编程指南。1.2 功能描述按照本编程指南所描述的标准，商户交易网站可以呼叫调用，支持功能包括签约、解约请求、挂单、撤单交易、实时成交、追加货款交易、确认付款交易、退货交易、批量撤单、批量成交、批量交易结果查询、到期支付，并且具备接收信用支付平台结果响应等功能。接口采用数字证书的方式来保证商户与信用支付平台间的身份验证、中间信息传递的完整性，以便进行电子商务安全当中非常重要的交易身份辨识、不可抵赖、防止篡改等功能。1.3 总体架构图2. 接口开发软件包说明银行提供的接口开发软件包 TrustPayClient-MARKET-PHP-Vx.x.x.zip（x.x.x为接口开发软件包的版本号）包含下列文档。文件名称说明/docs/农行网上支付平台-交易市场商户接口编程指南-PHP-Edition-Vx.x.pdf本文件/lib/EMarketClient-Vx.x.x.jar农行网上支付平台商户端接口Java软件包。/lib/WebServices_market_php_vx.x.jar农行网上支付平台商户端Web Services接口范例软件包。/lib/ABCMerchantMarket.properties接口配置文件/lib/jakarta-tomcat-5.0.28-market-yyyymmdd.tar.gz供参考的Tomcat应用服务器，包含相关配置/lib/api_market.phpPhp接口/demo/Merchant.html接口范例首页/demo/SignUpReq.php签约请求交易php范例页面1/demo/SignUpQuery.php签约请求交易php范例页面2/demo/ SignOffReq.php解约请求交易php范例页面1/demo/ SignOffQuery.php解约请求交易php范例页面2/cert/abc.truststore生产环境农行根证书/cert/abctest.truststore测试环境农行根证书/cert/trustpay.cer生产环境网上支付平台证书/cert/TrustPayTest.cer测试环境网上支付平台证书其他范例页面和文档参考“信用平台商户接口编程指南-Java_Edition-V2.1.0.doc”备注：由于php接口是对原有java接口基础上的进一步封装，所以需要参考java接口的相关文档和范例3. 安装步骤3.1 安装前检查1、本接口软件包采用JDK 1.4 标准，php5标准，请检查已经安装了php5和jdk1.4或以上版本的jvm。3.2 系统配置本文档以jdk1.5.0_18版本为JVM，jakarta-tomcat-5.0.28作为Web Services服务器，axis1.3作为SOAP解析引擎为例，介绍如何在linux平台下构建商户端Web Services服务器环境及部署接口应用。1、下载jakarta-tomcat-5.0.28，解压缩后放置安装目录下，下载axis-src-1_3，将axis文件夹放入$CATALINA_HOMEwebapps目录下。注：均已提供在“供参考的Tomcat应用服务器”中。2、安装jdk1.5.0_18。在catalina.sh中设置环境变量：export JAVA_HOME=/opt/IBM/was6admin/jdk1.5.0_18(根据实际安装路径来设置)export JAVA_OPTS=" -Xms256m -Xmx1024m"3、在$CATALINA_HOMEbin下命令行方式下，键入：./catalina.sh start启动服务器，然后在浏览器中键入地址http:/127.0.0.1:8080/axis/，查看能否正常启动。3.3 Web Services接口应用配置1、将银行提供的接口开发软件包TrustPayClient-MARKET-PHP-Vx.x.x.zip（x.x为接口开发软件包的版本号）解压缩到商户自定的安装目录中。2、请参考农行网上支付平台 -商户使用手册 V1.0登录网上支付平台下载商户交易证书，并将商户交易证书保存到服务器的硬盘或签名服务器中。3、将商户的证书文件夹Certificate放入$CATALINA_HOMEbin目录下，包括商户服务器证书*.pfx，农行根证书abc.truststore(生产环境证书，测试环境证书为abctest.truststore)和支付平台证书TrustPay.cer (生产环境证书，测试环境证书为TrustPayTest.cer)。4、将ABCMerchantMarket.properties文件放置到$CATALINA_HOMEwebappsaxisWEB-INFclasses目录下，该文件包含银行端访问地址，商户id,相关证书路径，证书密码的配置，日志路径等。商户需要注意进行正确的配置（具体参考配置文件说明）。将java接口包EMarketClient-Vx.x.x.jar文件放入$CATALINA_HOMEwebappsaxisWEB-INFlib下。5、将Web Services接口包WebServices_market_php_vx.x.jar放入$CATALINA_HOMEwebappsaxisWEB-INFlib下。在lib下加入包log4j-1.2.8.jar，dom4j-1.6.1.jar，jsse.jar，commons-httpclient-3.0.1.jar，commons-codec-1.3.jar。6、将Web Services配置文件server-config.wsdd放入$CATALINA_HOMEwebappsaxisWEB-INF中。7、修改$CATALINA_HOMEwebappsaxisWEB-INF的web.xml文件，添加log4j初始化的servlet配置，并在该目录下建立文件夹config，放置log4j.properties配置文件（该文件中，可以指定web services段代码日志输出格式及输出地址）。这里我们默认的日志是放在$CATALINA_HOMElogs下。8、重新启动tomcat应用服务器。9、通过php调用web services接口，从而与农行电子商务系统进行交互。注：以上 配置均已提供在“供参考的Tomcat应用服务器”中，以供参考。3.4 配置测试应用1、配置WebApp，指向接口软件包安装目录demo。2、开启浏览器进入 http:/your.server.name/your.virtual.directory/Merchant.html，确定接口软件包是否已正确安装及配置。4. 配置文件说明配置段参数名称数值类型说明信用支付平台系统配置段*请依照银行的指示设定TrustPayConnectMethod字符串信用支付平台通讯方式http：使用HTTP通讯方式https：使用HTTPS通讯方式（必需）TrustPayServerName字符串信用支付平台服务器名可以使用服务器的域名或服务器的IP地址TrustPayServerPort数字信用支付平台交易端口TrustPayNewLine数字信用支付平台接口特性1 或 2TrustPayServerTimeOut数字信用支付平台服务超时时间 毫秒TrustPayTrxURL字符串信用支付平台交易网址TrustPayCertFile字符串信用支付平台证书TrustStoreFile字符串农行根证书文件TrustStorePassword字符串农行根证书文件密码商户资料段MerchantID字符串商户编号商户系统配置段LogPath字符串日志文件存放绝对目录。*请勿输入文件名MerchantKeyStoreType数字证书储存媒体0: File1: 硬件签名服务器MerchantCertFile字符串商户证书储存目录档名当KeyStoreType=0时，必须设定。必须为PKCS#12的文件格式。MerchantCertPassword字符串商户私钥加密密码当KeyStoreType=0时，必须设定。SignServerIP字符串签名服务器IP地址当KeyStoreType=1时，必须设定。SignServerPort数字签名服务器端口当KeyStoreType=1时，必须设定。SignServerPassword字符串签名服务器密码当KeyStoreType=1时，必须设定。5. 范例交易说明在java接口的相关说明文档中，已经给出了如何利用农行提供的java接口包进行商户接口开发的说明，请参考“信用平台商户接口编程指南-Java_Edition-V2.1.0.doc”。php商户由于不能直接在程序中调用农行java接口，所以需要通过一个中间件间接调用农行java接口，本文档以交易市场中典型的签约和解约交易为例，介绍如何进行对农行java接口包的间接调用。注意：由于php系统商户接口开发是对java接口包进行的一个封装调用，所以商户在开发过程中，需要首先熟悉java接口包的使用，运行java接口包中的demo页面。5.1 交易流程本节将说明商户交易平台如何与网上支付平台通信，来完成交易的过程。5.1.1 Web Services技术的引入由于php商户在php程序中不能直接调用农行提供的java接口包，所以我们需要一种机制使得可以在php程序中间接调用java接口包。Web Services技术就可以提供这样一种功能。Web Services技术是由业界领袖IBM、Microsoft等公司倡导使用，并由国际标准组织W3C、ws-i等制定了SOAP、WSDL等协议和规范，使得Web Services技术可以将已有的功能代码进行封装发布，凡遵循Web Services技术规范的其他平台和程序都可以通过SOAP协议进行访问。所以，将农行java接口利用Web Services技术进行功能封装，就可以在php程序中进行跨平台、跨语言访问。下面，本文档将交易市场中常用的签约解约功能进行Web Services封装，并通过php程序进行跨平台调用访问，商户开发人员可以参考这两支交易，进行其它接口功能的开发。5.1.2 签约和解约交易签约或解约交易因为需要三方的配合（客户、商户交易网站、信用支付平台），且交易流程是分两阶段进行，所以商户交易平台针对每个交易需要开发两个主要的程序才能完成整个签约或解约交易流程，此两支程序为“签约或解约请求程序”及“签约或解约结果接收程序”。交易流程如下图所述：5.2 交易开发说明5.2.1 开发环境的配置1、商户模拟系统：Window php开发环境安装：1）安装php1.5版本2）配置php环境（C:WINDOWSphp.ini），添加soap支持（修改php.ini配置文件中extension=php_soap.dll），中文支持（php.ini中修改：extension_dir = "C:/php/ext"，ext目录中放入php_iconv.dll）2、Web Services环境：linuxjava开发环境：1)安装jdk1.52)安装eclipse开发环境（eclipse 3.2）3)安装Tomcat应用服务器（jakarta-tomcat-5.0.28）备注：商户模拟系统和Web Services环境既可以部署在Windows平台，也Linux平台上，本文档以上述配置环境为例进行说明。5.2.2 编写web services接口函数编写Web Services接口函数可以参考java接口包中提供的demo页面代码，将这些demo中的java代码翻译到一个java接口函数中。具体如下：1、签约请求签约请求的Web Services接口函数编写需要参考java接口包中的SignUpQuery.jsp，该jsp文件中，将客户输入的参数进行封装，然后调用农行java接口，从而与农行电子商务系统进行交互。 SignUpQuery.jsp文件的代码如下：<% page contentType="text/html; charset=gb2312" %><% page import = "com.hitrust.trustpay.client.market.*" %><% page import = "com.hitrust.trustpay.client.*" %><% page import = "com.hitrust.trustpay.envelop.ResponseEnvelop" %><% page import = "com.hitrust.trustpay.envelop.IParameterTagName" %><% request.setCharacterEncoding("GBK");response.setHeader("Cache-Control", "no-cache"); %><%/1、取得客户签名信息String tRequestID = request.getParameter("RequestID");String tCustSignInfo = request.getParameter("CustSignInfo");String tCustName = request.getParameter("CustName");String tMerchantName = request.getParameter("MerchantName");String tNeedTwoCheck = request.getParameter("NeedTwoCheck");/2、生成签约请求对象sSignUpRequest tRequest = new SignUpRequest(); tRequest.setCustSignInfo(tCustSignInfo); /客户签名信息（必要信息） tRequest.setRequestID(tRequestID); /请求流水号（必要信息）tRequest.setBusinessID(IBusinessType.MARKET);tRequest.setFunctionID(IFunctionID.MARKET_SIGNUP);tRequest.setCustName(tCustName);/客户名称（必要信息） tRequest.setMerchantName(tMerchantName);/交易市场名称（必要信息）tRequest.setNeedTwoCheck(tNeedTwoCheck);/是否需要双人复核 /3、传送商户身份验证请求并取得结果TrxResponse tResponse = tRequest.postRequest();String sReturnMsg = tResponse.getErrorMessage();String sReturnCode = tResponse.getReturnCode(); %><HTML><HEAD><TITLE>中国农业银行</TITLE></HEAD><BODY BGCOLOR='#FFFFFF' TEXT='#000000' LINK='#0000FF' VLINK='#0000FF' ALINK='#FF0000'><table><tr><td><b>客户签约</b></td></tr><% /4、判断签约结果状态，进行后续操作if (tResponse.isSuccess() String sMerchantID = tResponse.getMerchantID();String sFunctionID = tResponse.getFunctionID();String sCustomer = tResponse.getCustomerNo();String sFunctionName = "签约交易"%> <tr><td><%=sFunctionName %>交易成功</td> </tr> <tr><td>商户编号： <%=sMerchantID%></td> </tr> <tr><td>客户编号： <%=sCustomer%></td> </tr> <tr><td>交易返回结果： <%=sReturnMsg%></td> </tr><%else %> <tr><td>交易失败</td> </tr> <tr><td>错误代码： <%=sReturnCode%></td> </tr> <tr><td>错误信息： <%=sReturnMsg%></td> </tr><% %></table><br><a href='Merchant.html'>回商户首页</a></BODY></HTML>根据此jsp demo文件，我们编写的签约Web Services接口函数signUp_php如下：/* * * author tongyizhu * 在提供给Web Services php客户端调用的接口中，返回值result以数组形式进行传递，其中result0中存储农行客户端接口请求成功返回 * 的实质内容，result1存储标识请求是否成功的一个布尔型变量，result2中存储农行客户端接口请求的返回码，result3存储农行客户端接口请求的 * 错误信息 */public Object signUp_php(String tCustSignInfo,String tRequestID,String tCustName,String tMerchantName,String tNeedTwoCheck) logger.debug("In signUp_php");logger.debug("Parameters:");logger.debug("tCustSignInfo:"+ tCustSignInfo+ "#tRequestID:"+ tRequestID+ "#tCustName:"+ tCustName+ "#tMerchantName:"+ tMerchantName+ "#tNeedTwoCheck:"+ tNeedTwoCheck);Object result = new Object4;/1、生成签约请求对象sSignUpRequest tRequest = new SignUpRequest(); tRequest.setCustSignInfo(tCustSignInfo); /客户签名信息（必要信息） tRequest.setRequestID(tRequestID); /请求流水号（必要信息）tRequest.setBusinessID(IBusinessType.MARKET);tRequest.setFunctionID(IFunctionID.MARKET_SIGNUP);tRequest.setCustName(tCustName);/客户名称（必要信息） tRequest.setMerchantName(tMerchantName);/交易市场名称（必要信息）tRequest.setNeedTwoCheck(tNeedTwoCheck);/是否需要双人复核 / 4、传送直接支付请求并取得支付网址TrxResponse tResponse = tRequest.postRequest();String sReturnMsg = tResponse.getErrorMessage();String sReturnCode = tResponse.getReturnCode(); String sMerchantID = tResponse.getMerchantID();String sFunctionID = tResponse.getFunctionID();String sCustomer = tResponse.getCustomerNo();if (tResponse.isSuccess() /6、支付请求提交成功，将客户端导向支付页面logger.debug("MerchantID->" + sMerchantID);logger.debug("Customer->" + sCustomer);logger.debug("ReturnMsg->" + sReturnMsg);Object data1 = new Object3; /返回信息result0 = data1;data10 = sMerchantID;data11 = sCustomer;data12 = sReturnMsg;result1 = new Boolean(true); else result1 = new Boolean(false);result2 = tResponse.getReturnCode();result3 = tResponse.getErrorMessage();logger.info("ReturnCode = " + tResponse.getReturnCode() + "");logger.info("ErrorMessage = " + tResponse.getErrorMessage() + "");return result;可见，在jsp文件中，商户传递的所有参数，如请求流水号（tRequestID）是通过如下代码从请求中读取的。而Web Services接口函数由于是供其他程序调用的，所以这些参数是通过函数参数的方式传入的。tRequestID = request.getParameter("RequestID");和jsp程序中相仿，在signUp_php接口函数中，也是通过将所有输入参数封装成java接口包中的SignUpRequest对象，然后调用postRequest（）方法与农行电子商务系统进行交互，从而得到农行系统的返回结果。signUp_php接口函数通过将农行系统返回的结果封装在result对象数组中，返回给php系统，php系统提取出返回结果，进行下一步的操作。2、解约请求解约请求与签约请求类似，需要参考java接口包中的SignOffQuery.jsp，该jsp文件中，将客户输入的参数进行封装，然后调用农行java接口，从而与农行电子商务系统进行交互。 SignOffQuery.jsp文件的代码如下：<% page contentType="text/html; charset=gb2312" %><% page import = "com.hitrust.trustpay.client.market.*" %><% page import = "com.hitrust.trustpay.client.*" %><% page import = "com.hitrust.trustpay.envelop.ResponseEnvelop" %><% page import = "com.hitrust.trustpay.envelop.IParameterTagName" %><% request.setCharacterEncoding("GBK");response.setHeader("Cache-Control", "no-cache"); %><%/1、取得客户签名信息String tRequestID = request.getParameter("RequestID");String tCustSignInfo = request.getParameter("CustSignInfo");String tCustName = request.getParameter("CustName");String tMerchantName = request.getParameter("MerchantName");String tCustomer = request.getParameter("Customer");/2、生成签约请求对象SignUpRequest tRequest = new SignUpRequest(); tRequest.setCustSignInfo(tCustSignInfo); /客户签名信息（必要信息）tRequest.setRequestID(tRequestID); /请求流水号（必要信息）tRequest.setCustomer(tCustomer);tRequest.setBusinessID(IBusinessType.MARKET);tRequest.setFunctionID(IFunctionID.MARKET_SIGNOFF);tRequest.setCustName(tCustName);/客户名称（必要信息） tRequest.setMerchantName(tMerchantName);/交易市场名称（必要信息）/3、传送商户身份验证请求并取得结果TrxResponse tResponse = tRequest.postRequest();String sReturnMsg = tResponse.getErrorMessage();String sReturnCode = tResponse.getReturnCode(); String sCustomer = tResponse.getCustomerNo();%><HTML><HEAD><TITLE>中国农业银行</TITLE></HEAD><BODY BGCOLOR='#FFFFFF' TEXT='#000000' LINK='#0000FF' VLINK='#0000FF' ALINK='#FF0000'><table><tr><td><b>客户解约</b></td></tr><% /4、判断签约结果状态，进行后续操作if (tResponse.isSuccess() String sMerchantID = tResponse.getMerchantID();String sFunctionID = tResponse.getFunctionID();String sFunctionName = "解约交易"%> <tr><td><%=sFunctionName %>交易成功</td> </tr> <tr><td>商户编号： <%=sMerchantID%></td> </tr> <tr><td>交易返回结果： <%=sReturnMsg%></td> </tr> <tr><td>客户编号： <%=sCustomer%></td> </tr><%else %> <tr><td>解约失败</td> </tr> <tr><td>错误代码： <%=sReturnCode%></td> </tr> <tr><td>错误信息： <%=sReturnMsg%></td> </tr> <tr><td>客户编号： <%=sCustomer%></td> </tr><% %></table><br><a href='Merchant.html'>回商户首页</a></BODY></HTML>根据此jsp demo文件，我们编写的签约Web Services接口函数signOff_php如下：/* * * author tongyizhu * 在提供给Web Services php客户端调用的接口中，返回值result以数组形式进行传递，其中result0中存储农行客户端接口请求成功返回 * 的实质内容，result1存储标识请求是否成功的一个布尔型变量，result2中存储农行客户端接口请求的返回码，result3存储农行客户端接口请求的 * 错误信息 */public Object signOff_php(String tCustSignInfo,String tRequestID,String tCustomer,String tCustName,String tMerchantName) logger.debug("In signOff_php");logger.debug("Parameters:");logger.debug("tCustSignInfo:"+ tCustSignInfo+ "#tRequestID:"+ tRequestID+ "#tCustomer:"+ tCustomer+ "#tCustName:"+ tCustName+ "#tMerchantName:"+ tMerchantName);Object result = new Object4;/1、生成签约请求对象sSignUpRequest tRequest = new SignUpRequest(); tRequest.setCustSignInfo(tCustSignInfo); /客户签名信息（必要信息） tRequest.setRequestID(tRequestID); /请求流水号（必要信息）tRequest.setCustomer(tCustomer);tRequest.setBusinessID(IBusinessType.MARKET);tRequest.setFunctionID(IFunctionID.MARKET_SIGNOFF);tRequest.setCustName(tCustName);/客户名称（必要信息） tRequest.setMerchantName(tMerchantName);/交易市场名称（必要信息）/ 4、传送直接支付请求并取得支付网址TrxResponse tResponse = tRequest.postRequest();String sReturnMsg = tResponse.getErrorMessage();String sReturnCode = tResponse.getReturnCode(); String sCustomer = tResponse.getCustomerNo();String sMerchantID = tResponse.getMerchantID();String sFunctionID = tResponse.getFunctionID();if (tResponse.isSuccess() /6、支付请求提交成功，将客户端导向支付页面logger.debug("客户编号(Customer)->" + sCustomer);logger.debug("商户编号(MerchantID)->" + sMerchantID);logger.debug("交易返回结果(ReturnMsg)->" + sReturnMsg);Object data1 = ne