支付平台接入开发手册java - 商户支付_h

1、 支付平台接入开发手册 中国金融认证中心2009 年 10 月 21 日版权声明：本文档的版权属于中国金融认证中心自修改、拷贝或以其它方式使用本文档中的内容。 ，任何人或组织未经许可，不得擅1 文档修订记录本文档会随时保持更新，请与中国金融认证中心支付业务部索要最新版本。2版本 内容 日期 编写 审核 1.3 定稿 2009/10/21 崔莹峰 张行 1.17 1112 接口增加 note 字段 2013/7/22 熊飞 目录CFCA 提供的资料4客户自行准备的资料4配置文件说明5程序编写7系统初始化7Tx1111-商户订单支付（直通车）（异步交易）8Tx1112-商户订单支付（不要确认）（异

2、步交易）11Tx1115-商户订单支付（非结算直通车）（异步交易）13Tx1118-商户订单支付状态改变（同步交易）15Tx1119-商户订单支付状态变更（收款行）（同步交易）17Tx1120-商户订单支付交易查询（同步交易）19Tx1121-付款账户信息查询（同步交易）21Tx1131-商户订单退款（同步交易）23Tx1132-商户订单退款查询（同步交易）25Tx1133-商户订单支付原路退款（同步交易）27Tx1138-商户订单退款结果报文（同步交易）29Tx1810-交易对账单（同步交易）31Tx1840-监管银行交易对账（同步交易）333 资料CFCA 提供的资料客户自行准备的资料4资

3、料 文件说明 Web 容器 符合 Servlet2.4 规范 URL 用来接收支付平台直接通过 服务器发送的成功支付 报文。如果采用了市场订单结算，则也用来接收市场订单结算确认 报文。 文件名称 文件说明 手册 开发手册（java）.pdf 本文档，商户接入编程指南 API payment-x.x.x.x.jar 商户 API tools-x.x.x.jar 商户 API 依赖的工具包 配置文件 系统配置文件统一保存到指定目录中，使系统初始化程 序可以访问。 payment.ini 系统参数配置文件 xxx.pfx 商户证书文件，含私钥，用于交易报文签名。 xxx.cer 支付平台证书，用于验

4、证支付平台报文签名。 程序范例 titutionRef.rar 模拟商户系统，供开发人员编程参考。 银行信息 银行相关信息 包括支持的银行列表，银行 logo，及银行编码。 配置文件说明 payment.ini5配置段 参数名称 参数说明 机构签名证书和口令 my.keystore.filename 机构交易签名证书文件名 my.keystore.password 机构交易签名证书口令 支付平台公钥证书 payment.certificate.filename 支付平台公钥证书 支付平台接口地址 payment.url 支付交易地址（异步交易） tx.url 非支付交易地址（同步交易） 支持

5、SSL 选项 useDefaultSSLSocketFactory 是否使用默认的SSLSocketFactory trust.keystore.filename 信任证书链的密钥库文件 trust.keystore.password 信任证书链的密钥库口令 web.xml需要将支付平台提供的 payment.config 目录位置和 system.config 目录位置配置在 web.xml 中，其中 payment.config 目录用于存放证书(如:*.cer)以及初始化文件(如:payment.ini), system.config 目录用于存放 log 信息(如:log4j.xml)

6、,示例如下。 system.config.path/CFCA/Payment/titutionSimulator/system.configpayment.config.path/CFCA/Payment/titutionSimulator/payment.config6 程序编写系统初始化系统启动时，需要初始化一次（仅一次）系统配置信息，包含读取证书、地址 等。初始化支付环境代码如下：7/ 初始化支付环境，paymentConfigPath 为系统配置文件所在目录名 / 示例代码中为 payment.config PaymentEnvironment.initialize(paymentCo

7、nfigPath); Tx1111-商户订单支付（直通车）（异步交易）商户的支付页面由商户依据自己的业务需求自行开发，此处仅描述基本的处理逻辑。付款人在商户页面中确认订单，执行支付操作时，商户页面把支付请求提交到负责支付处理的程序，我们的范例提供了三支处理程序：Tx1111.jsp、Tx1111.java 和 Request.jsp 。Tx1111.java8/ 1.取得参数 StringtitutionID = request.getParameter(titutionID); String paymentNo = request.getParameter(PaymentNo); long

8、amount = Long.parseLong(request.getParameter(Amount); String payerID = !request.getParameter(PayerID).equals()?request.getParameter(PayerID).trim():null; String payerName = !request.getParameter(PayerName).equals()?request.getParameter(PayerName).trim():n ull; String settlementFlag = !request.getPar

9、ameter(SettlementFlag).equals()?request.getParameter(SettlementFlag).t rim():null; String usage = !request.getParameter(Usage).equals()?request.getParameter(Usage).trim():null; String remark = request.getParameter(Remark); String notificationURL = request.getParameter(NotificationURL); String bankID

10、 = request.getParameter(BankID); int accountType = Integer.parseInt(request.getParameter(AccountType); / 2.创建交易请求对象 Tx1111Request tx1111Request = new Tx1111Request(); tx1111Request.settitutionID(titutionID); tx1111Request.setPaymentNo(paymentNo); tx1111Request.setAmount(amount); Request.jsp9 functio

11、n doSubmit() document.form1.submit(); /此处依商户的逻辑显示相应的页面 /编写 Form，把 message 和 signature 提交到支付平台支付接口地址 % %tx1111Request.setPayerID(payerID); tx1111Request.setPayerName(payerName); tx1111Request.setSettlementFlag(settlementFlag); tx1111Request.setUsage(usage); tx1111Request.setRemark(remark); tx1111Requ

12、est.setNotificationURL(notificationURL); tx1111Request.setBankID(bankID); tx1111Request.setAccountType(accountType); / 3.执行报文处理tx1111Rcess(); / 4.将参数放置到 request 对象 request.setAttribute(message, tx1111Request.getRequestMessage(); request.setAttribute(signature, tx1111Request.getRequestSigna

13、ture(); request.setAttribute(action, PaymentEnvironment.paymentURL); / 5.转向 Request.jsp 页面 request.getRequestDispatcher(/Request.jsp).forward(request, response); 我们的范例使用了 3 支程序来处理商户发起的同步交易，这 3 支程序按照先后顺序依次执行：10Tx1111.jsp显示支付要素输入页面 Tx1111.java生成支付请求报文，并将支付请求报文转向到 Request.jspRequest.jsp这是一个自提交页面，接收到 Tx

14、1111 支付报文后， 自动提交到支付平台支付接口 Tx1112-商户订单支付（不要确认）（异步交易）业务逻辑同 Tx1111，不同的只是需要在支付平台选择银行和支付类型，我们的范例提供了三支处理程序：Tx1112.jsp、Tx1112.java 和 Request.jsp。下面只列了 Tx1112.java 处理逻辑，其余可参考商户订单支付（直通车）说明。Tx1112.java11/ 1.取得参数 StringtitutionID = request.getParameter(titutionID); String paymentNo = request.getParameter(Payme

15、ntNo); long amount = Long.parseLong(request.getParameter(Amount); String payerID = !request.getParameter(PayerID).equals()?request.getParameter(PayerID).trim():null; String payerName = !request.getParameter(PayerName).equals()?request.getParameter(PayerName).trim():n ull; String settlementFlag = !re

16、quest.getParameter(SettlementFlag).equals()?request.getParameter(SettlementFlag).t rim():null; String usage = !request.getParameter(Usage).equals()?request.getParameter(Usage).trim():null; String remark = request.getParameter(Remark); String note = !request.getParameter(Note).equals()?request.getPar

17、ameter(Note).trim():null; String notificationURL = request.getParameter(NotificationURL); / 2.创建交易请求对象 Tx1112Request tx1112Request = new Tx1112Request(); tx1112Request.settitutionID(titutionID); tx1112Request.setPaymentNo(paymentNo); tx1112Request.setAmount(amount); tx1112Request.setPayerID(payerID)

18、; 12tx1112Request.setPayerName(payerName); tx1112Request.setSettlementFlag(settlementFlag); tx1112Request.setUsage(usage); tx1112Request.setRemark(remark); tx1112Request.setNote(note); tx1112Request.setNotificationURL(notificationURL); / 3.执行报文处理tx1112Rcess(); / 4.将参数放置到 request 对象 request

19、.setAttribute(message, tx1112Request.getRequestMessage(); request.setAttribute(signature, tx1112Request.getRequestSignature(); request.setAttribute(action, PaymentEnvironment.paymentURL); / 5.转向 Request.jsp 页面 request.getRequestDispatcher(/Request.jsp).forward(request, response); Tx1115-商户订单支付（非结算直通

20、车）（异步交易）商户的支付页面由商户依据自己的业务需求自行开发，此处仅描述基本的处理逻辑。付款人在商户页面中确认订单，执行支付操作时，商户页面把支付请求提交到负责支付处理的程序，我们的范例提供了三支处理程序：Tx1115.jsp、Tx1115.java 和 Request.jsp 。Tx1115.java13/ 1.取得参数 StringtitutionID = request.getParameter(titutionID); String paymentNo = request.getParameter(PaymentNo); long amount = Long.parseLong(re

21、quest.getParameter(Amount); String payerName = !request.getParameter(PayerName).equals()?request.getParameter(PayerName).trim():n ull; String settlementFlag = !request.getParameter(SettlementFlag).equals()?request.getParameter(SettlementFlag).t rim():null; String usage = !request.getParameter(Usage)

22、.equals()?request.getParameter(Usage).trim():null; String remark = request.getParameter(Remark); String notificationURL = request.getParameter(NotificationURL); String bankID = request.getParameter(BankID); int accountType = Integer.parseInt(request.getParameter(AccountType); / 2.创建交易请求对象 Tx1115Requ

23、est tx1115Request = new Tx1115Request(); tx1115Request.settitutionID(titutionID); tx1115Request.setPaymentNo(paymentNo); tx1115Request.setAmount(amount); tx1115Request.setPayerName(payerName); tx1115Request.setSettlementFlag(settlementFlag); 14tx1115Request.setUsage(usage); tx1115Request.setRemark(r

24、emark); tx1115Request.setNotificationURL(notificationURL); tx1115Request.setBankID(bankID); tx1115Request.setAccountType(accountType); / 3.执行报文处理tx1115Rcess(); / 4.将参数放置到 request 对象 request.setAttribute(message, tx1115Request.getRequestMessage(); request.setAttribute(signature, tx1115Reque

25、st.getRequestSignature(); request.setAttribute(action, PaymentEnvironment.paymentURL); / 5.转向 Request.jsp 页面 request.getRequestDispatcher(/Request.jsp).forward(request, response); Tx1118-商户订单支付状态改变（同步交易）Tx1118 包含前台页面和两种。请分别加以处理。商户处理订单支付状态改变的处理逻辑如下：我们的范例使用了 3 支程序来处理商户发起的同步交易，其中 ReceiveNoticePage.java

26、 和 Response.jsp 共同处理页面，ReceiveNotice. java 处理。 15ReceiveNoticePage.java处理支付平台返回的支付结果成功报文（页面）Response.jsp显示支付平台返回报文 / 1.取得参数 String message = request.getParameter(message); String signature = request.getParameter(signature); / 2.创建对象 NoticeRequest noticeRequest = new NoticeRequest(message, signature)

27、; Notice1118Request nr = new Notice1118Request(noticeRequest.getDocument(); / 3.执行报文处理 logger.debug(TxName = 商户订单支付状态变更); logger.debug(TxCode = 1118); logger.debug(titutionID= + nr.gettitutionID() + ); logger.debug(PaymentNo = + nr.getPaymentNo() + ); logger.debug(Amount = + nr.getAmount() + ); logg

28、er.debug(Status = + nr.getStatus() + ); logger.debug(BankNotificationTime= + nr.getBankNotificationTime() + ); / 5.商户根据自己的业务要求编写相应的业务处理代码 / 6. 显示返回报文 request.setAttribute(plainText, noticeRequest.getResponsePlainText(); request.getRequestDispatcher(/Response.jsp).forward(request, response); 如果使用，接收到

29、支付结果成功报文，并正常处理商户交易后，需要返回支付平台成功响应。16/响应支付平台 PrintWriter out = response.getWriter(); String plainText = new NoticeResponse().getMessage(); String base64Text = new String(Base64.encode(plainText.getBytes(StringUtil.DEFAULT_CHARSET), StringUtil.DEFAULT_CHARSET); out.print(base64Text); out.flush(); out.c

30、lose(); ReceiveNotice.java处理支付平台返回的支付结果成功报文（） Tx1119-商户订单支付状态变更（收款行）（同步交易） Tx1119 只有。商户订单支付状态变更（收款行）的处理逻辑如下：17/ 1.取得参数 String message = request.getParameter(message); String signature = request.getParameter(signature); / 2.创建对象 NoticeRequest noticeRequest = new NoticeRequest(message, signature); Not

31、ice1119Request nr = new Notice1119Request(noticeRequest.getDocument(); / 3.执行报文处理 logger.debug(TxName = 商户订单支付状态变更(监管银行); logger.debug(TxCode = 1119); logger.debug(BranchID= + nr.getBranchID () + ); logger.debug(titutionID= + nr.gettitutionID() + ); logger.debug(PaymentNo= + nr.getPaymentNo() + ); l

32、ogger.debug(PayerID= + nr.gePayerID() + ); logger.debug(PayerName = + nr.getPayerName() + ); logger.debug(Amount = + nr.getAmount() + ); logger.debug(Status = + nr.getStatus() + ); logger.debug(Usage = + nr.getUsage() + ); logger.debug(PaidTime = + nr.getPaidTime() + ); logger.debug(Remark = + nr.ge

33、tRemark() + ); / 5.商户根据自己的业务要求编写相应的业务处理代码 /响应支付平台 /1119 的响应报文包含 PaymentNo，要特殊判断，不能使用公共的 NoticeResponse Notice1119Response notice1119Response = new Notice1119Response(); notice1119Response.setPaymentNo(nr.getPaymentNo(); plainText = notice1119Rcess(); PrintWriter out = response.getWriter()

34、; 我们的范例使用了 ReceiveNotice. java 处理。18ReceiveNotice.java处理支付平台返回的支付结果成功报文（）String base64Text = new String(Base64.encode(plainText.getBytes(StringUtil.DEFAULT_CHARSET), StringUtil.DEFAULT_CHARSET); out.print(base64Text); out.flush(); out.close(); Tx1120-商户订单支付交易查询（同步交易）商户通过该接口查询订单支付交易状态，我们的范例提供了 3 支处理程

35、序：Tx1120.jsp、Tx1120.java 和 Response.jsp，其中 Response.jsp 将支付平台返回报文 base64 解码后以明文显示。业务逻辑如下。Tx1120.java19/ 1.取得参数 StringtitutionID = request.getParameter(titutionID); String paymentNo = request.getParameter(PaymentNo ); / 2.创建交易请求对象 Tx1120Request tx1120Request = new Tx1120Request(); tx1120Request.setti

36、tutionID(titutionID); tx1120Request.setPaymentNo(paymentNo); / 3.执行报文处理tx1120Rcess(); / 4.与支付平台进行通讯 TxMessenger txMessenger = new TxMessenger(); / 0:message; 1:signature String respMsg = txMessenger.send(tx1120Request.getRequestMessage(), tx1120Request.getRequestSignature(); / 5.交易结果处理 0:m

37、essage; 1:signature Tx1120Response tx1120Response = new Tx1120Response(respMsg0, respMsg1); / 6. 如果返回正常报文 if (2000.equals(tx1120Response.getCode() /商户根据自己的业务要求编写相应的业务处理代码( titutionID= + tx1120Response.get titutionID() + ); (PaymentNo= + tx1120Response.getPaymentNo() + ); logger

38、.info(Amount= + tx1120Response.getAmount() + ); (Remark= + tx1120Response.getRemark() + ); 我们的范例使用了 3 支程序来处理商户发起的同步交易，这 3 支程序按照先后顺序依次执行：20Tx1120.jsp显示交易要素输入页面 Tx1120.java生成交易请求报文 Response.jsp将支付平台返回报文 base64 解码后以明文显示 (Status= + tx1120Response.getStatus() + ); (BankNo

39、tificationTime= + tx1120Response.getBankNotificationTime() + ); / 7. 显示返回报文 request.setAttribute(plainText, tx1120Response.getResponsePlainText(); request.getRequestDispatcher(/Response.jsp).forward(request, response); Tx1121-付款账户信息查询（同步交易）商户通过该接口查询付款账户信息，我们的范例提供了 3 支处理程序：Tx1121.jsp、 Tx1121.java 和 R

40、esponse.jsp，其中 Response.jsp 将支付平台返回报文 base64 解码后以明文显示。业务逻辑如下。Tx1121.java21/ 1.取得参数 StringtitutionID = request.getParameter(titutionID); String paymentNo = request.getParameter(PaymentNo ); / 2.创建交易请求对象 Tx1121Request tx1121Request = new Tx1121Request(); tx1121Request.settitutionID(titutionID); tx1121

41、Request.setPaymentNo(paymentNo); / 3.执行报文处理tx1121Rcess(); / 4.与支付平台进行通讯 TxMessenger txMessenger = new TxMessenger(); / 0:message; 1:signature String respMsg = txMessenger.send(tx1121Request.getRequestMessage(), tx1121Request.getRequestSignature(); / 5.交易结果处理 0:message; 1:signature Tx1121Re

42、sponse tx1121Response = new Tx1121Response(respMsg0, respMsg1); / 6. 如果返回正常报文 if (2000.equals(tx1121Response.getCode() /商户根据自己的业务要求编写相应的业务处理代码( titutionID= + tx1121Response.get titutionID() + ); (PaymentNo= + tx1121Response.getPaymentNo() + ); (PayerAccountName= + tx

43、1121Response.getPayerAccountName()+ ); 我们的范例使用了 3 支程序来处理商户发起的同步交易，这 3 支程序按照先后顺序依次执行：22Tx1121.jsp显示交易要素输入页面 Tx1121.java生成交易请求报文 Response.jsp将支付平台返回报文 base64 解码后以明文显示 (PayerAccountNumber= + tx1121Response. getPayerAccountNumber ()+ ); (PayerBranchName= + tx1121Response.getPayerBr

44、anchName()+ ); (PayerProvince= + tx1121Response.getPayerProvince()+ ); (PayerCity= + tx1121Response.getPayerCity()+ ); / 7. 显示返回报文 request.setAttribute(plainText, tx1121Response.getResponsePlainText(); request.getRequestDispatcher(/Response.jsp).forward(request, response); Tx11

45、31-商户订单退款（同步交易）商户通过该接口对某笔支付交易（前提是该交易已经支付成功）执行退款操作，我们的范例提供了 3 支处理程序：Tx1131.jsp、Tx1131.java 和 Response.jsp，其中 Response.jsp 将支付平台返回报文 base64 解码后以明文显示。下面只列出了处 理逻辑，其余可参考商户订单支付交易查询。Tx1131.java23/ 1.取得参数 StringtitutionID = request.getParameter(titutionID); String serialNumber = request.getParameter(SerialN

46、umber); String paymentNo = request.getParameter(PaymentNo); long amount = Long.parseLong(request.getParameter(Amount); String remark = request.getParameter(Remark); int accountType = Integer.parseInt(request.getParameter(AccountType); String paymentAccountName = request.getParameter(PaymentAccountNa

47、me); String paymentAccountNumber = request.getParameter(PaymentAccountNumber); String bankID = request.getParameter(BankID); String accountName = request.getParameter(AccountName); String accountNumber = request.getParameter(AccountNumber); String branchName = request.getParameter(BranchName); Strin

48、g province = request.getParameter(Province); String city = request.getParameter(City); / 2.创建交易请求对象 Tx1131Request tx1131Request = new Tx1131Request(); tx1131Request.settitutionID(titutionID); tx1131Request.setSerialNumber(serialNumber); tx1131Request.setPaymentNo(paymentNo); tx1131Request.setAmount(

49、amount); 24tx1131Request.setRemark(remark); tx1131Request.setAccountType(accountType); tx1131Request.setPaymentAccountName(paymentAccountName); tx1131Request.setPaymentAccountNumber(paymentAccountNumber); BankAccount bankAccount = new BankAccount(); bankAccount.setBankID(bankID); bankAccount.setAcco

50、untName(accountName); bankAccount.setAccountNumber(accountNumber); bankAccount.setBranchName(branchName); bankAccount.setProvince(province); bankAccount.setCity(city); tx1131Request.setBankAccount(bankAccount); / 3.执行报文处理tx1131Rcess(); / 4.与支付平台进行通讯 TxMessenger txMessenger = new TxMessenge

51、r(); / 0:message; 1:signature String respMsg = txMessenger.send(tx1131Request.getRequestMessage(), tx1131Request.getRequestSignature(); / 5.交易结果处理 0:message; 1:signature Tx1131Response tx1131Response = new Tx1131Response(respMsg0, respMsg1); / 6 如果返回正常报文 if (2000.equals(tx1131Response.getCode() logg

52、(Message= + tx1131Response.getMessage()+ ); /商户根据自己的业务要求编写相应的业务处理代码 / 7. 显示返回报文 request.setAttribute(plainText, tx1131Response.getResponsePlainText(); request.getRequestDispatcher(/Response.jsp).forward(request, response); Tx1132-商户订单退款查询（同步交易）商户通过该接口执行退款交易查询操作，我们的范例提供了 3 支处理程序：Tx1132.jsp、Tx1132.java 和 Respo