<商户端Java接口编程指南>
编号
项目电子商务网上交易市场平台项目
类别项目
密级<内部>
目录
1简介 (1)
1.1目的 (1)
1.2功能描述 (1)
1.3总体架构图 (1)
2接口开发软件包说明 (2)
3安装步骤 (2)
3.1安装前检查 (2)
3.2接口开发软件包安装 (2)
3.3接口开发软件包配置 (3)
3.4配置测试应用 (3)
4配置文件说明 (3)
5交易说明 (4)
5.1交易流程说明 (4)
5.1.1客户发起交易 (4)
5.1.2商户发起交易 (5)
5.2交易说明 (5)
5.2.1签约请求 (5)
5.2.2解约请求 (6)
5.2.3实时支付交易 (7)
5.2.4付款交易 (7)
5.2.5账单申请 (8)
5.2.6账单支付 (9)
5.2.7手续费查询 (9)
5.2.8修改客户结算账户 (10)
5.2.9交易资金专用账户余额查询 (10)
5.3程序范例 (11)
5.3.1签约交易范例 (11)
5.3.2解约交易范例 (13)
5.3.3实时支付交易范例 (16)
5.3.4退/付款交易范例 (18)
5.4报文结构说明 (20)
5.5交易代码含义对照表 (21)
5.6主机交易响应代码含义对照表 (21)
5.7商户端接口包本地错误代码含义对照表 (25)
<商户接口编程指南>
? Copyright ABC. 2008 第 1 页
1 简介
1.1 目的
提供给商户交易网站开发人员，根据中国农业银行网上交易市场支付平台提供的商户端开发软件包实现功能的编程指南。
1.2 功能描述
按照本编程指南所描述的标准，商户交易网站可以呼叫调用银行提供的交易接口功能，并且具备接收银行系统结果响应等功能。
接口采用数字证书的方式来保证商户与网上交易市场支付平台间的身份验证、中间信息传递的完整性，以便进行电子商务安全当中非常重要的交易身份辨识、不可抵赖、防止篡改等功能。
1.3 总体架构图
2接口开发软件包说明
银行提供的接口开发软件包EMarketClient-Java-Vx.x.x.zip（x.x.x为接口开发软件包的版本号）包含下列文档。
3安装步骤
3.1安装前检查
1)本接口软件包采用JDK 1.5 标准。
2)请确定服务器已经安装了下列软件：Sun JSSE V1.0 或更高的版本
3.2接口开发软件包安装
1)将银行提供的接口开发软件包EMarketClient-Java-Vx.x.x.zip（x.x.x为接口开发软件包的版
本号）解压缩到商户自定的安装目录中。
2)请参考《农行网上交易市场支付平台-商户使用手册V1.0》登录网上交易市场支付平台下
载商户交易证书，并将商户交易证书保存到服务器的硬盘或签名服务器中。
? Copyright ABC. 2008 第 2 页
? Copyright ABC. 2008 第 3 页
3) 将lib 目录下的EMarketClient -Vx.x.jar 、commons-codec-1.3.jar 、commons-httpclient-3.0.1.jar 、
dom4j-1.6.1.jar,jsse.jar 加入应用服务器的CLASSPATH 中。
3.3 接口开发软件包配置
开启接口配置文件ABCMerchantMarket.properties ，依照银行提供的信息设定相对应的参数。并将ABCMerchantMarket.properties 所在的目录加入应用服务器的CLASSPATH 中。详细配置文件的说明请参考下一章的说明。
3.4 配置测试应用
1) 配置WebApp ，指向接口软件包安装目录\demo 。
2) 开启浏览器进入 https://www.doczj.com/doc/3718217482.html,/your.virtual.directory/Merchant.html ，确定接口软件
包是否已正确安装及配置。
4 配置文件说明
? Copyright ABC. 2008 第 4 页
5 交易说明
农行网上交易市场支付平台商户接口采用面向对象的方式设计，商户在交易的过程中会需要使用到各个不同的类来完成所需要的交易。交易流程
本节将说明商户交易平台如何与网上交易市场支付平台通信，来完成交易的过程。
5.1 交易流程说明
5.1.1 客户发起交易
客户发起交易，指客户通过商户交易网站完成的交易，此类交易需要由客户发起，商户交易网站在收到客户交易请求后，把请求发送到银行系统，接收银行系统返回结果，同时通知客户交易结果。此类交易主要有：签约、解约、挂单、撤单、追加货款、确认付款、实时支付、客户授权、账单支付等等。交易流程如下图所述（签约、解约为例）：
5.1.2商户发起交易
商户发起交易，指不需要客户的参与，由商户交易系统自行发起的交易请求。此类交易包括有：付款、实时支付交易以及各种查询交易等等。交易流程分别如下图所述：
5.2交易说明
1)客户签约、解约请求交易
客户在交易市场网站上，选择签约、解约交易。
2)实时支付交易
客户在交易市场网站上，交纳会员费时，选择实时支付由客户发起请求。
3)账单申请交易
交易市场填写相关信息，发起账单申请交易请求，。
4)账单支付交易
客户在交易市场网站上，选择账单发起账单支付请求。
5.2.1签约请求
客户由交易市场发起签约交易，用于客户、商户与电子商务网上交易市场平台的相关协议，电子商务平台对客户、商户进行身份验证并记录签约信息，步骤说明如下：
1，生成签约请求对象
包：com.hitrust.trustpay.client.market
类名：SignUpRequest
SignUpRequest tRequest = new SignUpRequest();
2，设置签约请求对象属性
RequestID交易请求流水号（必要信息）
MerchantID交易市场在农行的注册商户号（必要信息）
MerchantName交易市场在农行的注册名称（必要信息）
NeedTwoCheck双人复核标志（值“2”为需要双人复核，可选）
CustSignInfo客户签名信息（必要信息）
? Copyright ABC. 2008 第 5 页
tRequest.setCustSignInfo(tCustSignInfo); //设置客户签名信息（必要信息）
tRequest.setRequestID(tRequestID); //设置请求流水号（必要信息）
tRequest.setBusinessID(IBusinessType.MARKET); // 设置交易类型
tRequest.setFunctionID(IFunctionID.MARKET_SIGNUP);//设置交易ID
tRequest.setCustName(tCustName); //设置客户名称（必要信息）
tRequest.setMerchantName(tMerchantName); //设置交易市场名称（必要信息）
tRequest.setNeedTwoCheck(tNeedTwoCheck); //设置是否需要双人复核标志3，调用签约请求对象的postRequest()方法传送签约请求并取得交易结果对象
4，使用交易结果对象的isSuccess()方法辨别交易是否成功
5，若交易成功，则商户可以取得交易结果对象的其他属性来进行后续的作业
ReturnMsg 签约返回信息
6, 若交易失败,使用交易结果对象的getReturnCode ()及getErrorMessage()方法取得交易失败原因。
7, 交易结果对象的getReturnCode ()所回传的响应码请参考《附录二、响应码一览表》的说明。
5.2.2解约请求
客户由交易市场发起解约交易，用于客户、商户与银行电子商务网上交易市场平台相关协议，电子商务网上交易市场平台对客户、商户进行身份验证并记录解约信息，步骤说明如下：1，生成解约请求对象
包：com.hitrust.trustpay.client.market
类名：SignUpRequest
SignUpRequest tRequest = new SignUpRequest();
2，设置解约请求对象属性
RequestID交易请求流水号（必要信息）
CustSignInfo客户户签名信息（必要信息）
MerchantID商户农行注册商户号（必要信息）
MerchantName商户农行注册商户名（必要信息）
Customer客户号（必要信息）
CustName客户名（必要信息）
tRequest.setCustSignInfo(tCustSignInfo); //客户签名信息（必要信息）
tRequest.setRequestID(tRequestID); //请求流水号（必要信息）
tRequest.setCustomer(tCustomer); //设置客户号
tRequest.setBusinessID(IBusinessType.MARKET);//设置交易类型
tRequest.setFunctionID(IFunctionID.MARKET_SIGNOFF);//设置交易ID
tRequest.setCustName(tCustName); //客户名称（必要信息）
tRequest.setMerchantName(tMerchantName); //交易市场名称（必要信息）3，调用解约约请求对象的postRequest()方法传送解约请求并取得交易结果对象
? Copyright ABC. 2008 第 6 页
? Copyright ABC. 2008 第 7 页
4，使用交易结果对象的isSuccess()方法辨别交易是否成功
5，若交易成功，则商户可以取得交易结果对象的其他属性来进行后续的作业 ReturnMsg 签约返回成功信息
6, 若交易失败,使用交易结果对象的getReturnCode ()及getErrorMessage()方法取得交易失败原因。
7, 交易结果对象的getReturnCode ()所回传的响应码请参考《附录二、响应码一览表》的说明。
5.2.3 实时支付交易
客户在交易市场发起请求，用于向交易市场支付相关的费用，步骤说明如下：
1, 生成实时支付请求对象
包：com.hitrust.trustpay.client.market 类名： PayRequest
PayRequest tPayRequest = new PayRequest(); 2, 设定实时支付请求对象的属性
RequestID 流水号（必要信息） Customer 客户号（必要信息） PayAmount 支付金额（必要信息） CustSignInfo 客户签名信息（必要信息） CustSignInfo2 客户签名信息2（当客户为企业客户且签约时设置为双人复核的，
此项为必要信息）
tPayRequest.setRequestID(tRequestID); //请求流水号（必要信息） tPayRequest.setFunctionID("0009");
tPayRequest.setCustSignInfo(tCustSignInfo); //客户签名信息（必要信息） tPayRequest.setCustSignInfo2(tCustSignInfo2); //客户签名信息（必要信息） tPayRequest.setPayAmount(tPayAmount); //会员费（必要信息） tPayRequest.setCustomerNo(tCustomer); //客户号（必要信息） tPayRequest.setMessage(tMessage);
3, 使用实时支付请求对象的postRequest()方法传送请求并取得交易结果对象 4, 使用交易结果对象的isSuccess()方法辨别支付请求是否成功
5, 若交易成功，则商户可以取得交易结果对象的其他属性来进行后续的作业 ReturnMsg 签约返回信息
6, 若请求失败，可以使用交易结果对象的getReturnCode ()及getErrorMessage()方法取得交易失败原因。
7, 交易结果对象的getReturnCode ()所回传的响应码请参考《附录二、响应码一览表》的说明。
5.2.4 付款交易
? Copyright ABC. 2008 第 8 页
市场发起请求，用于交易市场向客户支付相关的费用，步骤说明如下：
1, 生成退、付款请求对象
包：com.hitrust.trustpay.client.market 类名： PayRequest
PayRequest tPayRequest = new PayRequest(); 2, 设定请求对象的属性
tPayRequest.setRequestID(tRequestID); //设置请求流水号 tPayRequest.setFunctionID("0030"); //设置交易ID tPayRequest.setPayAmount(tPayAmount); //设置交易金额 tPayRequest.setCustomerNo(tCustomer); //设置客户号
tPayRequest.setReqSeqTrace(tOrgReqSeqTrace); //设置原交易流水号（10时设置） tPayRequest.setFeeAmount(tFeeAmount); //设置手续费金额
tPayRequest.setFlag(tTrnxType); //设置交易标识（10退款、11付款 ）
（本模式只支持付款）
tPayRequest.setMessage(tMsg); //设置交易信息端（可选） 3, 使用请求对象的postRequest()方法传送请求并取得交易结果对象 4, 使用交易结果对象的isSuccess()方法辨别支付请求是否成功
5, 若交易成功，则商户可以取得交易结果对象的其他属性来进行后续的作业 ReturnMsg 签约返回信息
6, 若请求失败，可以使用交易结果对象的getReturnCode ()及getErrorMessage()方法取得交易失败原因。
7, 交易结果对象的getReturnCode ()所回传的响应码请参考《附录二、响应码一览表》的说明。
5.2.5 账单申请
交易交易市场发起交易请求，步骤如下：
1，生成账单请求对象
包：com.hitrust.trustpay.client.market 类名：PayOrderRequest
PayOrderRequest tPayRequest = new PayOrderRequest(); 2，设置账单请求对象属性
tPayRequest.setFunctionID("0025"); //交易ID tPayRequest.setRequestID(tRequestID); //请求流水号（必要信息）
tPayRequest.setBuyCustName(tBuyCustName); //客户签名信息（必要信息） tPayRequest.setBuyCustNo(tBuyCustNo); //客户签名信息（必要信息） tPayRequest.setSaleCustName(tSaleCustName);//客户名称 tPayRequest.setSaleCustNo(tSaleCustNo);//客户号2 tPayRequest.setOrderNo(tOrderNo);//账单号
tPayRequest.setOrderType(tOrderType);//账单类型
tPayRequest.setPayAmount(tPayAmount); // 账单金额
? Copyright ABC. 2008 第 9 页
tPayRequest.setOrdrMg(tMessage);//账单信息 tPayRequest.setFeeFlag(tFeeType);//手续费标志
3，调用交易请求对象的postRequest()方法传送请求并取得交易结果对象 4，使用交易结果对象的isSuccess()方法辨别交易是否成功
5，若交易成功，则商户可以取得交易结果对象的其他属性来进行后续的作业 ReturnMsg 签约返回成功信息
6, 若交易失败,使用交易结果对象的getReturnCode ()及getErrorMessage()方法取得交易失败原因。
7, 交易结果对象的getReturnCode ()所回传的响应码请参考《附录二、响应码一览表》的说明。
5.2.6 账单支付
客户在交易市场发起交易，步骤如下：
1，生成账单支付请求对象
包：com.hitrust.trustpay.client.market 类名：PayOrderRequest
PayOrderRequest tPayRequest = new PayOrderRequest(); 2，设置账单支付请求对象属性
tPayRequest.setFunctionID("0026"); tPayRequest.setRequestID(tRequestID); //请求流水号（必要信息） tPayRequest.setCustSignInfo(tCustSignInfo); //客户签名信息（必要信息） tPayRequest.setCustSignInfo2(tCustSignInfo2); //客户签名信息2（必要信息） tPayRequest.setOrderNo(tOrderNo);// 账单号 tPayRequest.setPayAmount(tPayAmount); // 支付金额
3，调用交易请求对象的postRequest()方法传送请求并取得交易结果对象 4，使用交易结果对象的isSuccess()方法辨别交易是否成功
5，若交易成功，则商户可以取得交易结果对象的其他属性来进行后续的作业 ReturnMsg 签约返回成功信息
6, 若交易失败,使用交易结果对象的getReturnCode ()及getErrorMessage()方法取得交易失败原因。
7, 交易结果对象的getReturnCode ()所回传的响应码请参考《附录二、响应码一览表》的说明。
5.2.7 手续费查询
交易市场发起交易，步骤如下：
1，生成手续费查询请求对象
包：com.hitrust.trustpay.client.market
? Copyright ABC. 2008 第 10 页
类名：PayOrderFeeQueryRequest
PayOrderFeeQueryRequest tPayRequest = new PayOrderFeeQueryRequest(); 2，设置手续费查询请求对象属性
tPayRequest.setFunctionID(tFunction); //交易ID tPayRequest.setRequestID(tRequestID); //请求流水号（必要信息） tPayRequest.setOrderNo(tOrderNo);//账单号（必要信息）
3，调用交易请求对象的postRequest()方法传送请求并取得交易结果对象 4，使用交易结果对象的isSuccess()方法辨别交易是否成功
5，若交易成功，则商户可以取得交易结果对象的其他属性来进行后续的作业 ReturnMsg 签约返回成功信息
6, 若交易失败,使用交易结果对象的getReturnCode ()及getErrorMessage()方法取得交易失败原因。
7, 交易结果对象的getReturnCode ()所回传的响应码请参考《附录二、响应码一览表》的说明。
5.2.8 修改客户结算账户
交易市场发起交易，步骤如下：
1，生成修改客户结算账户请求对象 包：com.hitrust.trustpay.client.market 类名：ModifCustAccNoRequest
ModifCustAccNoRequest tPayRequest = new ModifCustAccNoRequest(); 2，设置修改客户结算账户请求对象属性 tPayRequest.setFunctionID("0031"); tPayRequest.setRequestID(tRequestID); //请求流水号（必要信息） tPayRequest.setNewCustAccNo(tNewNo); //客户签名信息（必要信息） tPayRequest.setOldCustAccNo(tOldNo); //客户签名信息（必要信息） tPayRequest.setCustomer(tCustNo); tPayRequest.setCustType(tCustType);
3，调用交易请求对象的postRequest()方法传送请求并取得交易结果对象 4，使用交易结果对象的isSuccess()方法辨别交易是否成功
5，若交易成功，则商户可以取得交易结果对象的其他属性来进行后续的作业 ReturnMsg 签约返回成功信息
6, 若交易失败,使用交易结果对象的getReturnCode ()及getErrorMessage()方法取得交易失败原因。
7, 交易结果对象的getReturnCode ()所回传的响应码请参考《附录二、响应码一览表》的说明。
5.2.9 交易资金专用账户余额查询
交易市场发起交易，步骤如下：
? Copyright ABC. 2008 第 11 页
1，生成交易资金专用账户余额查询请求对象 包：com.hitrust.trustpay.client.market 类名：AccInfoQueryRequest
AccInfoQueryRequest tRequest = new AccInfoQueryRequest(); 2，设置交易资金专用账户余额查询请求对象属性 tRequest.setRequestID(tRequestID); tRequest.setRequestID(tRequestID); tRequest.setContractId(tContractID); tRequest.setCustomer(tBuyerCustNo); tRequest.setBuyerSignInfo(tBuyerSignInfo); tRequest.setBuyerSignInfo2(tBuyerSignInfo2);
3，调用交易请求对象的postRequest()方法传送请求并取得交易结果对象 4，使用交易结果对象的isSuccess()方法辨别交易是否成功
5，若交易成功，则商户可以取得交易结果对象的其他属性来进行后续的作业 ReturnMsg 签约返回成功信息
6, 若交易失败,使用交易结果对象的getReturnCode ()及getErrorMessage()方法取得交易失败原因。
7, 交易结果对象的getReturnCode ()所回传的响应码请参考《附录二、响应码一览表》的说明。
5.3 程序范例
5.3.1 签约交易范例
<%@ 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、生成签约请求对象s
? Copyright ABC. 2008 第 12 页
SignUpRequest 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(); %>
| 客户签约 |
| <%=sFunctionName %>交易成功 |
| 商户编号： <%=sMerchantID %> |
| 客户编号： <%=sCustomer %> |
| 交易返回结果： <%=sReturnMsg %> |
| 交易失败 |
| 错误代码： <%=sReturnCode %> |
| 错误信息： <%=sReturnMsg %> |
5.3.2 解约交易范例
<%@ 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(); %>
| 客户解约 |
| <%=sFunctionName %>交易成功 |
| 商户编号：<%=sMerchantID%> |
| 交易返回结果：<%=sReturnMsg%> |
| 客户编号：<%=sCustomer%> |
| 解约失败 |
| 错误代码：<%=sReturnCode%> |
| 错误信息：<%=sReturnMsg%> |
| 客户编号：<%=sCustomer%> |
? Copyright ABC. 2008 第14 页