农行网上支付平台B2C接口编程指南PHPEditionV10.docx
《农行网上支付平台B2C接口编程指南PHPEditionV10.docx》由会员分享，可在线阅读，更多相关《农行网上支付平台B2C接口编程指南PHPEditionV10.docx（69页珍藏版）》请在冰豆网上搜索。
农行网上支付平台B2C接口编程指南PHPEditionV10
中国农业银行网上支付平台
B2CPHP商户接口编程指南
JavaEdition
V1.0
修订历史纪录
日期
版本
说明
作者
2009/06/19
V1.0
初稿
童益柱
1.简介
1.1目的
提供商户端交易网站通过中国农业银行网上支付平台提供的商户端开发软件包实现功能的编程指南。
1.2功能描述
按照本编程指南所描述的标准，商户交易网站可以呼叫调用，支持功能包括支付请求、取消支付、退货、订单查询、交易对账单下载，并且具备接收网上支付平台支付结果响应的功能。
接口采用电子证书的方式来保证商户与网上支付平台间的身份验证、中间信息传递的完整性，以便进行电子商务安全当中非常重要的交易身份辨识、不可抵赖、防止篡改等功能。
1.3总体架构图
2.接口开发软件包说明
银行提供的接口开发软件包TrustPayClient-B2C-PHP-Vx.x.x.zip（x.x.x为接口开发软件包的版本号）包含下列文档。
文件名称
说明
/docs/农行网上支付平台-B2C商户接口编程指南-PHP-Edition-Vx.x.pdf
本文件
/docs/农行网上支付平台-商户使用手册.pdf
商户使用手册
/docs/农行网上支付平台-USBKey安装及使用手册.pdf
USBKey安装及使用手册
/docs/农行网上支付平台-商户端软件包-FAQ.pdf
商户开发中常见问题解答
/lib/TrustPayClient-Vx.x.x.jar
农行网上支付平台商户端接口Java软件包。
/lib/WebServices_b2c_php_vx.x.jar
农行网上支付平台商户端WebServices接口软件包。
/lib/TrustMerchant.properties
接口配置文件
/lib/jakarta-tomcat-5.0.28-b2c-yyyymmdd.tar.gz
Tomcat应用服务器，包含相关配置
/lib/api.php
Php接口
/demo/Merchant.html
接口范例首页
/demo/MerchantPayment.html
支付请求交易范例页面
/demo/MerchantPayment.php
支付请求交易范例程序
/demo/MerchantResult.jsp
支付结果接收范例程序
/demo/ReciveServerPage.jsp
直接接收服务器支付结果范例程序
/demo/MerchantVoidPayment.html
取消支付交易范例页面
/demo/MerchantVoidPayment.php
取消支付交易范例程序
/demo/MerchantQueryOrder.html
订单查询交易范例页面
/demo/MerchantQueryOrder.php
订单查询交易范例程序
/demo/MerchantRefund.html
退货交易范例页面
/demo/MerchantRefund.php
退货支付交易范例程序
/demo/MerchantTrxSettle.html
交易对账单下载范例页面
/demo/MerchantTrxSettle.php
交易对账单下载范例程序
/demo/MerchantTrxSettleByHour.html
交易对账单下载范例页面
/demo/MerchantTrxSettleByHour.php
交易对账单下载范例程序
/demo/IdentityVerify.html
身份验证范例页面
/demo/IdentityVerify.php
身份验证范例程序
/demo/IdentityVerifyResult.jsp
身份验证结果接收范例程序
/demo/MerchantBatchSend.html
批量退款发送页面
/demo/MerchantBatchSend.php
批量退款发送程序
/demo/MerchantQueryBatch.html
批量退款结果查询页面
/demo/MerchantQueryBatch.php
批量退款结果查询程序
/cert/abc.truststore
农行根证书
/cert/trustpay.cer
网上支付平台证书
/ABCIcon/*.jpg
用于商户在自行开发的页面上，如果有指向农行网站的图片链接，请使用这些图片做为农行标识。
注意：
图片的整体尺寸可以根据需要进行缩放，但是图片的内容和比例大小不能修改。
3.安装步骤
3.1安装前检查
1、本接口软件包采用JDK1.3标准，php5标准。
2、请确定服务器已经安装了下列软件：
◆SunJSSEV1.0或更高的版本
3.2系统配置
本文档以jdk1.5.0_18版本为JVM，jakarta-tomcat-5.0.28作为WebServices服务器，axis1.3作为SOAP解析引擎为例介绍如何构建商户端WebServices服务器环境及部署接口应用。
1、下载jakarta-tomcat-5.0.28，解压缩后放置安装目录下，下载axis-src-1_3，将axis文件夹放入$CATALINA_HOME\webapps目录下。
2、安装jdk1.5.0_18。
在catalina.sh中设置环境变量：
exportJAVA_HOME=/opt/IBM/was6admin/jdk1.5.0_18（根据实际安装路径来设置）
exportJAVA_OPTS="-Xms256m-Xmx1024m"
3、在$CATALINA_HOME\bin下命令行方式下，敲入：
./catalina.shstart启动服务器，然后在浏览器中键入地址http:
//127.0.0.1:
8080/axis/，查看能否正常启动。
3.3WebServices接口应用配置
1、将银行提供的接口开发软件包TrustPayClient-B2C-PHP-Vx.x.x.zip（x.x为接口开发软件包的版本号）解压缩到商户自定的安装目录中。
2、请参考《农行网上支付平台-商户使用手册V1.0》登录网上支付平台下载商户交易证书，并将商户交易证书保存到服务器的硬盘或签名服务器中。
3、将商户的证书文件夹Certificate放入$CATALINA_HOME\bin目录下，包括商户服务器证书*.pfx，农行根证书abc.truststore（生产环境证书，测试环境证书为abctest.truststore）和支付平台证书TrustPay.cer（生产环境证书，测试环境证书为TrustPayTest.cer）。
4、将TrustMerchant.properties文件放置到$CATALINA_HOME\webapps\axis\WEB-INF\classes目录下，该文件包含银行端访问地址，商户id,相关证书路径，证书密码的配置，日志路径等。
商户需要注意进行正确的配置（具体参考配置文件说明）。
将该TrustPayClient-Vx.x.jar文件放入$CATALINA_HOME\webapps\axis\WEB-INF\lib下。
5、将WebServices接口包WebServices_b2c_php_vx.x.jar放入$CATALINA_HOME\webapps\axis\WEB-INF\lib下。
在lib下加入包jcert.jar，jnet.jar，jsse.jar。
6、将WebServices配置文件server-config.wsdd放入$CATALINA_HOME\webapps\axis\WEB-INF中。
7、修改$CATALINA_HOME\webapps\axis\WEB-INF的web.xml文件，添加log4j初始化的servlet配置，并在该目录下建立文件夹config，放置log4j.properties配置文件（该文件中，可以指定webservices段代码日志输出格式及输出地址）。
这里我们默认的日志是放在$CATALINA_HOME\logs下。
8、将支付结果文件MerchantResult.jsp放在$CATALINA_HOME\webapps\axis，这样支付成功后可通过这个页面回显给客户。
将身份验证结果文件IdentityVerifyResult.jsp放在$CATALINA_HOME\webapps\axis，这样可通过这个页面将验证结果回显给客户。
9、重新启动tomcat应用服务器。
10、通过php调用webservices接口，从而与农行电子商务系统进行交互。
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或2
TrustPayTrxURL
字符串
网上支付平台交易网址
TrustPayCertFile
字符串
网上支付平台证书
TrustStoreFile
字符串
农行根证书文件
TrustStorePassword
字符串
农行根证书文件密码
商户资料段
MerchantID
字符串
商户编号
商户系统配置段
LogPath
字符串
日志文件存放绝对目录。
*请勿输入文件名
MerchantKeyStoreType
数字
证书储存媒体
0:
File
1:
硬件签名服务器
MerchantCertFile
字符串
商户证书储存目录档名
当KeyStoreType=0时，必须设定。
必须为PKCS#12的文件格式。
MerchantCertPassword
字符串
商户私钥加密密码
当KeyStoreType0时，必须设定。
SignServerIP
字符串
签名服务器IP地址
当KeyStoreType=1时，必须设定。
SignServerPort
数字
签名服务器端口
当KeyStoreType=1时，必须设定。
SignServerPassword
字符串
签名服务器密码
当KeyStoreType=1时，必须设定。
5.交易说明
农行网上支付平台商户接口采用面向对象的方式设计，商户在交易的过程中会需要使用到各个不同的类来完成所需要的交易。
本章的说明着重在流程的说明，类的详细说明请参考《附录三、TrustPayClientPHP5API》。
。
5.1交易流程
本节将说明商户交易平台如何与网上支付平台通信，来完成交易的过程。
5.1.1支付交易
支付交易因为需要三方的配合（消费者、商户交易网站、网上支付平台），且交易流程是分两阶段进行，所以商户交易平台需要开发两个主要的程序才能完成整个支付的流程，此两支程序为“支付请求程序”及“支付结果接收程序”。
交易的过程根据支付结果的接收方式的不同而不同，两种交易流程分别如下图所述：
页面通知支付结果方式：
服务器通知支付结果方式：
5.1.2确保支付结果正确送达商户网站的措施
网上支付平台为了防止网络异常中断所造成的支付结果丢失，建议商户实现下列网上支付平台所提供的机制。
◆订单查询交易
针对未收到银行交易结果回复的订单，或银行响应交易状态未明的订单，商户可以在任何时刻主动发起订单查询请求（详细交易说明请参考5.7订单查询），查询订单（支付）的状态。
例如在商户网站提供消费者支付结果查询的功能，如该订单未收到网上支付平台交易结果，则调用网上支付平台的订单查询交易取得交易结果（订单状态），然后以取得的交易结果更新商户网站的支付状态。
◆通知商户支付成功
支付成功后，如果消费者浏览器安装了某些拦截弹出窗口软件（例如3721），那么支付结果接收页面有可能不会正常弹出，此时消费者可以点击【通知商户支付成功】按钮，重新发送支付结果到商户交易平台，确保商户能够收到网上支付平台的交易结果通知。
5.1.3其它交易
其它的交易（取消支付、退货、订单状态查询、交易对账单下载）只需要商户及网上支付平台的参与，交易的过程是实时响应，商户只需要简单的开发交易程序即可完成交易的过程。
交易过程如下图所述：
5.2交易使用时机
⏹支付请求交易
消费者在商户网站上购买商品，并选择网上支付时。
⏹支付结果接收
消费者在网上支付平台上进行在线支付的操作，支付成功后，网上支付平台会将支付的结果通知到商户指定的支付结果通知页面。
商户必须开发此页面，否则无法收到支付结果的通知。
⏹订单查询
针对未收到银行交易结果回复的订单，或银行响应交易状态未明的订单，商户可以发起订单查询请求，查询订单的状态。
网上支付平台的支付结果页面也会提供消费者通知商户支付成功的链接按钮，用来确定商户是否已经收到网上支付平台的通知。
商户必须开发此页面。
⏹取消支付
所有当日的订单（22:
00为切账时间）商户可以使用取消支付的交易来撤销已经支付成功的订单。
隔日的订单将无法取消支付，必须使用退货。
⏹退货
针对已经结帐的订单，商户可以使用退货的交易来退还交易金额给消费者。
退货的交易由商户自行发起，不需要消费者的参与。
⏹交易对账单下载
网上支付平台每日22:
00进行切账作业，切账作业后批次号将会累加。
商户可在每日早上08:
00后进行交易对账单的下载，确定是否有未回传的成功交易。
例如：
商户发起下载2003/11/20的交易对账单请求，网上支付平台将会回传2003/11/1922:
00到2003/11/2022:
00中间所有的成功交易。
5.3支付请求
当消费者在商户的网站购物确定订单后，选择使用网上支付付款。
商户首先提交支付请求给网上支付平台，接着将消费者的浏览器导到农行网上支付平台的支付页面。
消费者在网上支付平台上进行在线支付的操作，支付成功后，网上支付平台会将支付结果通知给商户，目前通知方式有两种：
◆页面通知：
网上支付平台会将支付的结果通知到商户指定的支付结果通知页面。
◆服务器通知：
网上支付平台会将支付的结果通过支付平台的服务器直接发送到商户知道的URL连接
提示：
开发过程中，当商户将消费者的浏览器导到农行网上支付平台的支付页面时，有可能会受到消费者安装了某些拦截弹出窗口软件（例如3721）的影响，所以提醒商户请选择正确的页面跳转方式（例如通过按钮点击或者重新刷新页面等方式）。
1、生成交易请求对象MerchantPaymentRequest
2、设定交易请求对象的属性
◆tOrderNo订单编号（必要信息）
◆tOrderDesc订单说明
◆tOrderDate订单日期（必要信息-YYYY/MM/DD）
◆tOrderTime订单时间（必要信息-HH:
MM:
SS）
◆tOrderAmountStr订单金额（必要信息）
◆tOrderURL订单查询网址（必要信息）
◆tProductType设定商品种类（必要信息）
◆tPaymentType设定支付类型（必要信息）
注意：
目前支付类型分为农行卡支付和国际卡支付以及贷记卡支付三种
如果商户设定了农行卡支付，成功提交支付请求后就会给消费者直接导向到农行卡支付页面；
如果商户设定了国际卡支付，成功提交支付请求后就会给消费者直接导向到国际卡支付页面。
如果商户设定了贷记卡支付，成功提交支付请求后就会给消费者直接导向到贷记卡支付页面。
◆tPaymentLinkType设定支付接入方式（必要信息）
注意：
目前支持三种接入方式，Internet网络接入，Mobile网络接入，数字电视网络接入，不同的支付方式会返回不同的支付处理页面。
◆tNotifyType设定支付结果通知方式（必要信息）
◆tResultNotifyURL支付结果地址（必要信息）
注意：
如果支付结果通知方式选择了页面通知，此处填写就是支付结果回传网址；
如果支付结果通知方式选择了服务器通知，此处填写的就是接收支付平台服务器发送响应信息的地址。
◆tMerchantRemarks商户备注信息
◆tOrderItems订单明细
3、生成支付请求对象MerchantPayment
4、使用支付请求对象的invoke（）方法传送支付请求并取得交易结果对象
5、使用交易结果对象的isSuccess属性辨别支付请求是否成功
6、若请求成功，可以使用交易结果对象MerchantPaymentResult的paymentURL属性取得支付页面网址，并将消费者的浏览器导向到此支付页面网址进行支付。
支付平台页面支持多种语言，如果商户需要将支付页面导向其他语种界面，支付页面URL网址需设定为：
getValue（"PaymentURL"）＋&language=语种代码
语种代码如下：
中文----------------------ZH
英文----------------------EN
法语----------------------FR
德语----------------------DE
韩语----------------------KO
语种代码不区分大小写，目前支付平台只支持中文和英文两种语言系统，如果不传入语种代码参数，则默认为中文。
7、若请求失败，可以使用交易结果对象的returnCode及ErrorMessage属性取得交易失败原因。
交易结果对象的returnCode所回传的响应码请参考《附录二、响应码一览表》的说明。
5.4两种接收支付结果方式的区别
消费者在网上支付平台上进行在线支付的操作，支付成功后，网上支付平台会将支付结果通知给商户，目前通知方式有两种：
通过显示给消费者的支付结果接收页面通知商户和通过支付平台服务器通知商户
5.4.1通过显示给消费者的支付结果接收页面通知商户
商户选择此种接收支付结果通知的方式，需要开发一个接收支付结果通知的页面。
商户在向网上支付平台发送交易请求的时候选择通过页面通知方式接收支付结果，传送给支付平台一个支付结果通知的页面地址；然后消费者在网上进行在线支付，如果支付成功后，网上支付平台会将支付结果信息通过显示给消费者的支付结果通知页面通知给商户。
交易流程如下：
5.4.2通过支付平台服务器通知商户
商户选择此种接收支付结果通知的方式，需要开发两支页面：
◆接收服务器通知的页面（ServerURL）
◆展示给消费者支付结果信息的页面（CustomerURL）
注意：
这两支页面的URL应该是在公网能访问的网址，而且端口号必须为80或者443（http默认端口为80；https默认端口为443）
商户在向网上支付平台发送交易请求的时候选择通过服务器通知的方式接收支付结果，传送给支付平台一个接收服务器通知的页面（ServerURL），此页面的HTML代码里应该包含一个准备展示给消费者支付结果的URL链接（CustomerURL）（注意：
链接之间需要用包含，具体代码参见附录一、C页面），然后消费者在网上进行在线支付，如果支付成功后，网上支付平台会将支付结果通知给商户，商户接收到支付结果信息后，必需将显示给消费者的页面URL（CustomerURL）链接返回给支付平台服务器，然后支付平台服务器把接收到的这个展示给消费者支付结果信息的页面弹出给消费者显示。
如果第一次通知向商户发送通知时发生下列情况时：
◆1、无法连接到指定的商户交易结果接收页面；
◆2、商户交易结果接收页面没有正确响应消费者支付结果URL。
系统将会在消费者的浏览器弹出一个新的窗口，并以此新窗口打开商户支付结果接收页面（ServerURL）。
为了保证在此状况下消费者还是可以看到正常的商户交易结果页面（CustomerURL），建议在ServerURL页面加上自动转向CustomerURL的脚本，此脚本范例请参考附录一、C页面。
5.4.3区别
采取通过页面通知的方式将支付结果通知给商户，如果消费者的浏览器里安装了一些弹出窗口拦截软件（例如：
3721），就会导致页面无法弹出，商户也就无法接收到通知消息；采用服务器通知的方法，网上支付平台会将支付结果消息通过服务器直接发送给商户指定的URL，而且发送失败以后可以重复发送，这样就保证了商户可以不受消费者本地设置的影响，正确的接收到支付结果通知。
5.5支付结果接收页面
消费者在网上支付平台上进行在线支付的操作，如果商户的支付结果通知方式选择了“页面通知”，那么当支付成功后，网上支付平台会将支付的结果发送到商户指定的支付结果通知页面；如果商户的支付结果通知方式选择了“服务器通知”，那么此页面就是网上支付平台服务器弹出显示给消费者的支付结果页面。
商户取得银行通知信息的步骤说明如下：
注意：
对于同一笔订单的支付结果信息，网上支付平台有可能会多次提交到商户指定的支付结果页面，所以提醒商户在开发过程中注意处理。
1、取得网上支付平台post的MSG参数
2、利用此参数生成支付结果对象com.hitrust.trustpay.client.b2c.PaymentResult
3、使用支付结果对象的isSuccess（）方法辨别支付是否成功
4、若支付成功，则商户可以取得支付结果对象的其他属性来进行后续的作业
◆OrderNo订单号
◆Amount订单金额
◆BatchNo交易批次号
◆VoucherNo交易凭证号（用于交易对账时使用）
◆HostDate银行交易日期（YYYY/MM/DD）
◆HostTime银行交易时间（HH:
MM:
SS）
◆MerchantRemarks商户备注信息（商户在支付请求时所提交的信息）
◆PayType消费者支付方式
◆NotifyType支付结果通知方式
5、若支付失败，可以使用支付结果对象的getReturnCode（）及getErrorMessage（）方法取得支付失败原因。
支付结果对象的getReturnCode（）所回传的响应码请参考《附录二、响应码一览表》的说明。
5.6取消支付请求
取消支付的交易由商户自行发起，不需要消费者的参与，银行对该交易的响应将立即回传。
商户发起取消支付交易的步骤说明如下：
1、生成交易请求对象MerchantVoidPaymentRequest
2、设定交易请求对象的属性
◆tOrderNo订单号（必要信息）
3、生成取消支付请求对象MerchantVoidPayment
4、调用取消支付请求对象的invoke（）方法传送取消支付请求并取得交易结果对象
5、使用交易结果对
升级会员 