企业官网建设流程全解析

简介：面向需要接入农业银行网银支付的 Java 开发人员，这套升级版接口文件与配套 Demo 同时涵盖接口文档和可运行示例，适合电商平台、在线服务商快速完成支付集成，也可作为了解网银支付对接流程的教学参考。压缩包共 147 个文件，整体大小约 5.1MB，其中以 class 编译类、jsp 动态页面、html 说明页面和 jar 依赖库为主，另有 properties 配置文件、cer 数字证书与 truststore 信任库，分别支撑核心支付逻辑、前端页面交互、文档浏览、运行环境依赖与安全通信校验，整体结构清晰，便于按模块查找所需内容。内容覆盖交易请求参数组装、数字签名、银行响应解析、异常处理与回调通知等关键环节；从已编译的类文件可看出，支付辅助功能已按加密、参数组装、数据校验等职责拆分，配合示例程序可完整了解从发起支付到订单结果同步的流程，二次开发时也能直接复用其中封装好的请求与校验逻辑。目前已有 2072 人学习下载，对于需要快速落地农行网银支付、降低排查成本的团队而言，具有较好的参考价值。

1. 农行web端网银支付Java接口：先搞清楚它到底长什么样

农行web端网银支付Java接口，说人话就是商户网站通过Java后端把订单信息签名打包，跳转到农行网银收银台，等用户完成支付后，农行再把结果回传给商户系统的这一整套接口文件和配套demo。很多人第一次接触时，以为拿到demo就能一个下午跑通，实际上十有八九卡在证书、商户号和回调地址这些和代码无关的地方。下面内容从接口文件构成、demo落地步骤、联调参数到常见坑，一次讲清楚。正在做电商、缴费、企业门户或者对公B2B订单的Java开发，照着这套思路走，能少熬几个通宵。

2. 接口文件和交易流程：动手前先分清三种形态和四件套

2.1 B2C、B2B和银企直连：web端支付接口的三种形态

农行的web端网银支付接口文件，不是只有一种。你在农行商户管理系统里提交申请时，银行会先问你是个人收款还是企业对公收款，这个选择直接决定你后续下载到的接口文档和demo是不是同一个版本。如果选错了形态，哪怕代码写得再对，支付页也进不去。

三种形态的核心区别，我用一张表来说清楚：

选型上我的建议是：如果你的用户是个人消费者，就选B2C，它的接口文件里带的是标准web端跳转demo，Java工程里一个Servlet加一个签名工具类就能跑起来。如果订单来自企业客户，而且对方需要从对公账户扣款，那就老老实实走B2B；不少银行B2B的web端接口会要求额外做企业客户绑定关系，不是简单发个表单就能支付。至于银企直连，它本质上是银行核心系统和商户财务系统的报文中转通道，不走浏览器，这份web端demo一般也用不上。

还有一种容易被混淆的情况：农行网银支付和代发工资、代扣是两套接口，前者是即时交易，后者是批量委托。标题里的web端网银支付，指的要么是B2C，要么是B2B的页面跳转型，代扣代发那类批量接口文件不是demo里能跑通的东西，别拿来做在线收款。

2.2 一次网银支付的完整时序：从下单到对账

不管拿到的是哪一版接口文件，web端网银支付的主流程都是固定的八步，我建议先把这个时序串起来再打开IDE写代码。

第一步，用户在商户网站点“去付款”，Java后端生成唯一订单号并落库，订单状态置为未支付。第二步，后端按银行要求的顺序组装报文字段，用商户证书私钥签名，动态生成一个隐藏表单页面。第三步，浏览器自动把表单POST到农行的支付入口，这一步用户能看到的只是收银台加载过程。第四步，用户在农行网银页面核对金额，输入密码或用K宝类硬件完成支付。第五步，农行同步跳回商户的returnUrl，这个页面只负责展示“支付完成”，绝对不能在这里改订单状态。第六步，农行后台向商户的notifyUrl发起异步通知，POST报文里携带订单号和签名，这是商户系统更新订单的唯一可靠依据。第七步，商户系统验签、判断幂等、在事务里更新订单状态，然后返回银行规定的成功标志。第八步，第二天银行生成对账文件，商户下载并与本地交易表核对，差异数据走清结算流程处理。

这八步里最容易翻车的是第五步和第六步的职责混淆。同步跳转在浏览器里能立刻看到，很多开发图省事就顺手在returnUrl里把订单改成已支付，结果异步通知晚到几分钟或者因为网络问题重发，订单状态被改来改去，月底对账对不上。正确做法是returnUrl只读参数做展示，notifyUrl里更新订单。

订单号和金额字段也要提前约定好。订单号在商户侧生成，银行会做重复校验，千万不要用当前毫秒时间戳直接当订单号，并发一高必重。金额字段更要看仔细，接口文档里会明确写单位是“元”还是“分”，有些老接口还要求两位小数但数值本身就是分，这两种情况差着两个数量级，联调时填错一个数量级，测试单可能还能走通一半，生产环境就是事故。

2.3 商户参数四件套：没凑齐别急着写代码

在打开demo源码之前，先确认以下四样东西是否都拿到了，缺一样，后面的联调都会变成玄学。

我一般会把四件套集中放在一个配置文件里，禁止散落在Java代码中。不同环境用不同的配置文件，测试环境用测试商户号，线上环境用线上商户号，两个环境哪怕只差一个数字，也会导致签名通过之后商户匹配失败。

配置文件大致长这样：

# config.properties 示例，按环境替换 merchant.merNo=商户号 merchant.merCode=柜台号 merchant.certPath=/opt/keys/merchant-test.pfx merchant.certPassword=证书密码 merchant.payUrl=文档里查到的支付入口地址 merchant.notifyUrl=https://www.example.com/pay/notify merchant.returnUrl=https://www.example.com/pay/result

注意：payUrl和notifyUrl的具体域名和路径，以你下载到的那版接口文件为准。不同时间段、不同一级分行给的文档版本可能有差异，测试环境地址通常也跟生产环境不一样，配置里单独留两个键更稳妥。

证书路径建议统一放到服务器约定目录，避免在Windows路径和Linux路径之间来回改。证书密码不要提交到Git仓库，测试环境可以用环境变量注入，线上环境务必用密钥管理或启动参数传入。回调地址在商户平台登记后，任何端口、路径、协议上的偏差都会导致银行找不到回调入口。

到这一步，接口文件的构成和商户参数已经清楚了，下一章开始真正把demo在本地跑起来。

3. 在本地把demo跑起来：最小Java落地步骤

3.1 先盘demo文件包：哪些能直接抄，哪些必须改

农行web端网银支付的Java demo，解压后通常是一套标准Web工程，里面四类东西分层很清楚。

第一类是文档，一般是PDF或Word，包含接口定义、报文规范、签名说明、错误码表，这是整个包里最有价值的文件，代码反而是次要的。第二类是银行提供的jar包，放在lib目录，里面封装了商户证书读取和非对称签名，个别版本也会有加解密的辅助类。第三类是示例代码，通常是一个或多个Servlet，展示支付请求、异步通知、订单查询的组装和解析方式。第四类是资源文件，包括配置文件和测试证书。

拿到包之后我建议先做三件事。第一，看文档版本号和日期，银行接口偶尔会调字段或交易码，网上博客写的两年后可能已经不对了。第二，看jar包和JDK内部包有没有最深层的依赖关系，JDK版本变了很容易在这里翻车。第三，直接搜“Signature”和“sign”，把签名相关代码单独摘出来，这是整个对接里唯一不可替换的自写部分，其他Servlet逻辑都是传输层的东西。

另外要认清一个事实：demo是演示性质，它默认你在本地环境跑通流程，所以日志是System.out、配置文件里直接明文密码、异常处理也是throw到页面。这些在生产环境全都要换掉，尤其日志必须换成logback或log4j2并落盘，因为支付回调的原始报文是排障时候的后悔药，System.out在Tomcat里重启就没了。

3.2 本地联调准备：JDK8、Tomcat和内网可达

演示工程最常见的运行环境是JDK8加Tomcat 8.5，这个组合对老jar包兼容性最好。如果你的电脑已经装了JDK17，也别急着卸载，在开发工具里给工程单独指定JDK8的JDK环境就行。老证书库和签名算法在JDK9以上偶尔会遇到JCE权限或算法提供者变化，用JDK8跑demo是最省事的选择。

把demo工程打包成war丢进Tomcat的webapps目录后，默认访问地址是本机8080端口。这里有个实际问题：银行的异步通知是从银行服务器发到你部署的地址，本机的localhost银行根本访问不到，所以联调阶段需要让本机端口能被公网访问。常见的做法是用内网穿透工具把8080端口暴露成一个公网HTTPS地址，然后把那个地址前缀登记为回调地址。

这个阶段还有两个小建议。第一，回调地址和支付完成后的跳转地址，在测试环境尽量用不同的路径，方便日志里区分来源。第二，本机联调时把Tomcat的访问日志打开，银行回调来了先看访问日志，再看业务日志，能快速判断是没到达还是到达了没处理成功。

3.3 支付请求的代码骨架：从订单到自动提交表单

支付请求这步，demo里一般是一个Servlet或Controller，接收本地订单号，查询订单，组装银行参数，签名，然后输出自动提交表单。下面这段代码是支付请求的骨架写法，字段名以你手上的接口文件为准：

@WebServlet("/pay") public class PayServlet extends HttpServlet { protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { String orderNo = req.getParameter("orderNo"); // 从订单服务读订单，必须保证订单存在且未支付 Order order = orderService.getByOrderNo(orderNo); if (order == null || order.isPaid()) { resp.sendRedirect("/pay/error.jsp?msg=订单状态异常"); return; } // 用LinkedHashMap保证字段顺序，签名拼接顺序依赖它 Map<String, String> params = new LinkedHashMap<>(); params.put("MerNo", merchantConfig.getMerNo()); params.put("OrderNo", order.getOrderNo()); params.put("TranType", "0"); // 0表示B2C消费，按文档定义取值 params.put("Amount", String.valueOf(order.getAmount())); // 注意金额单位 params.put("ProductInfo", order.getGoodsName()); params.put("ReturnUrl", merchantConfig.getReturnUrl()); params.put("NotifyUrl", merchantConfig.getNotifyUrl()); // 调用demo里的签名工具，传入证书路径和密码 String signature = SignatureUtil.sign( params, merchantConfig.getCertPath(), merchantConfig.getCertPassword()); params.put("Signature", signature); // 输出自动提交表单，页面保持loading状态 writeAutoSubmit(resp, merchantConfig.getPayUrl(), params); } }

逻辑说明：最核心的一行是签名调用，银行接收表单后会按同样规则重新计算签名，如果不匹配直接拒绝交易。LinkedHashMap在这里不是锦上添花，部分接口的签名原文是按参数拼接顺序组织的，顺序错一位验签就过不了，所以map的插入顺序必须和接口文档里的字段顺序一致。

参数说明：TranType在大多数B2C接口里用0表示消费，1或2可能是退款或查询，具体以文档里的交易类型定义表为准，不要凭记忆填。Amount字段要特别注意单位，有些版本用“分”，有些用“元”并保留两位小数，填错一个数量级，用户看到的支付金额就是错的，这是生产事故级别的问题。ProductInfo如果有中文，注意报文编码和银行侧约定编码要一致，常见的是UTF-8，个别老接口还是GBK，这类编码问题在现场联调时才暴露，提前确认能省半天时间。

writeAutoSubmit方法本身不复杂，就是把参数变成隐藏的input，再塞一个form和一个自动提交的script。有些接口版本还要求在表单里带一个商户柜台号或令牌字段，这块完全按文档来，不要自己发明。

3.4 异步回调验签，把订单状态改成已支付

异步通知是银行对商户系统发起的POST请求，请求内容组织方式和支付请求不一样，不要指望在上一节的Servlet里一起处理。回调处理的前几步就决定了这笔单子能不能安全落库：

@WebServlet("/notify") public class NotifyServlet extends HttpServlet { protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { // 1. 取出全部报文参数，按银行约定的顺序重组 Map<String, String> params = extractParams(req); // 2. 验签，证书用商户证书里的公钥部分 boolean verified = SignatureUtil.verify( params, merchantConfig.getCertPath(), merchantConfig.getCertPassword()); if (!verified) { resp.setStatus(400); return; } String orderNo = params.get("OrderNo"); // 3. 幂等：订单已支付就直接返回成功，避免重复通知重复入账 if (orderService.isPaid(orderNo)) { resp.getWriter().write(notifyConfig.getSuccessCode()); return; } // 4. 事务里更新订单状态，只允许未支付订单被更新为已支付 int updated = orderService.markPaid(orderNo, amount, paySeq); if (updated == 1) { resp.getWriter().write(notifyConfig.getSuccessCode()); } else { resp.setStatus(500); // 让银行稍后重试 } } }

逻辑说明：验签失败不能直接返回成功，也不能返回签名字样，最简单做法是回一个非2xx状态，让银行按重试机制再来一次。幂等判断在这里极其重要，银行通知机制是“没收到成功标志就重发”，同一笔订单在极短时间内收到两三次通知是常态。我的做法是先查订单状态，再执行update，并且把update语句写成只更新状态为未支付的记录，这样即使并发来了两个通知，同一时间点也不会改出脏状态。

返回值说明：银行要求商户处理成功返回约定的成功码，各家有差异，有的直接返回“OK”，有的要求特定字符串或标志位，一定要看文档里的原话。返回值写错，银行会认为处理失败继续重发，日志里会刷出一堆重复通知。另外要提醒一句：写响应时注意不要在多线程环境下共用同一个OutputStream的写法，Tomcat下每个请求各自拿Writer就行，别做静态共享。

4. 联调必调的几个参数：证书读取、交易码和回调地址

4.1 证书读取与签名方式：验签失败九成出在这里

农行web端网银支付的接口文件里，商户证书一般以PFX格式下发，少数版本也给JKS。demo里会有对应的证书加载工具类，但很多人把demo类复制到生产后，在证书读取这里先翻一次车。

PFX解析的核心逻辑如下：

// 证书加载和私钥提取，PKCS12格式 KeyStore keyStore = KeyStore.getInstance("PKCS12"); try (FileInputStream fis = new FileInputStream(certPath)) { keyStore.load(fis, password.toCharArray()); } // 获取证书别名，别名不确定时遍历keyStore.aliases() String alias = keyStore.aliases().nextElement(); PrivateKey privateKey = (PrivateKey) keyStore.getKey(alias, password.toCharArray()); // 签名：一般是SHA1withRSA，具体以文档为准 Signature signature = Signature.getInstance("SHA1withRSA"); signature.initSign(privateKey); signature.update(signSource.getBytes("UTF-8")); byte[] signed = signature.sign(); String signBase64 = Base64.getEncoder().encodeToString(signed);

参数说明：certPath和password来自配置文件，注意PFX的解析密码和签名时用的私钥密码通常是同一个，个别银行要求设置签名密码和证书加载密码两个值，打开接口资料确认一下。alias的获取不要用硬编码，PFX重新导出时别名可能是证书名也可能是随机串，遍历aliases取第一个能找到私钥的条目更稳。签名源字符串的编码必须和组装参数时一致，UTF-8和GBK混用会导致验签结果时好时坏，这是联调里最磨人的问题之一。

老接口里“RSA签名”这个说法很笼统，具体是SHA1withRSA还是MD5withRSA需要看接口文件版本的说明。优先用文档指定的算法，不要拿网上别的支付项目代码直接替换，摘要算法不一样，验签这一关永远过不了。另外，证书私钥是敏感资源，生产环境建议把PFX文件权限设成仅运行用户可读，密码通过启动参数或密钥服务注入，别放代码仓库。

4.2 交易码和报文字段：接口定义别靠猜

接口文件里有一张交易类型说明表，里面的交易码是字段取值的大头。支付请求、退款、订单查询、对账下载，每个功能对应不同交易码和不同必填字段，不要指望一个请求方法通吃所有功能。

我列一份常见字段清单，字段名以你手头文档为准：

接口定义里最容易踩雷的是OrderNo的唯一性约束。银行侧对订单号有重复校验，生产环境订单号必须全局唯一，时间戳加随机数这种方案并发高时可能出现重复，建议用数据库自增主键、分布式ID或业务前缀加序号。另外，退款接口的订单号和金额逻辑与支付不同，退款可以全额也可以部分，部分退款在银行侧的字段定义和渠道费率都会变，测试时务必覆盖部分退款场景。

交易码不要在代码里散落魔法值，建一个枚举类集中维护会省掉很多事。不同版本的接口文件，交易码完全相同但字段含义却变了，这种情况确实在银行接口里出现过，所以注释里一定要写接口文件版本号，两年前写的交易码枚举，今年升级后可能就失效了。

4.3 回调地址的工程约束：登记、HTTPS和重试

回调地址是银行主动连接的入口，它的工程约束和普通web接口不一样。

第一，银行要求商户登记的回调地址和实际报文里的NotifyUrl一致，否则直接不发通知。联调时如果总是收不到回调，第一件事不是查代码，而是去商户后台核对登记的地址和配置文件是否一字不差，包括协议、域名、路径、端口，甚至末尾斜杠。这些细节肉眼很难看出来，我的土办法是先从银行侧拉近期交易明细，确认测试单有没有支付成功，如果支付成功了却没回调，再怀疑登记问题。

第二，生产环境的回调地址基本必须走HTTPS。这里的证书和商户签名证书是两个概念，回调地址的HTTPS证书由商户自己配置，银行侧会对证书合法性做校验，免费证书有时在证书链解析上出问题，有条件就上可信证书，电商类商户大概率本来就有域名证书。

第三，回调处理要做到快速完结。银行通知是点对点HTTP，链路超时时间并不长，回调里做的数据库操作、事务提交、返回值打印都要控制在几十到一两百毫秒级别。如果回调里又去查第三方接口，比如查物流、发短信，会大幅增加超时概率，银行超时后会按自己的频率重发，这个重发可能带来重复订单入账。正确做法是把重活放到事务提交之后再异步处理，回调方法里只干和订单状态有关的最小操作。

联调阶段用抓包工具看web端请求和回调报文也很常见，比如fiddler这类工具可以把支付跳转和银行回调的报文完整导出来，对比签名原文顺序是不是和文档一致。注意抓包只能看到应用层报文，证书私钥绝不会出现在报文里，也绝不会通过网络传输。

这里特别提醒：回调的报文日志一定要落盘，包含原始报文和时间戳。翻日志比对银行重试的时间点，能发现很多测试环境复现不出来的问题。日志别拼在一个字符串里让多线程串行输出，否则会丢字段，排查时对不上号。

5. 农行网银支付Java接口避坑：4个让人血压升高的现场

5.1 报错“无此商户”：商户号和证书不是一套

现象：提交支付请求后，银行页面提示“无此商户”，业务日志里的返回报文也带着商户不存在的字样。

原因：商户号和证书不匹配。这个情况六成发生在换机器、换服务器或者重新下载证书之后。测试环境用测试商户号配了线上证书，或者线上环境配置文件的商户号和证书里内置的商户号不是同一套，银行端在验签通过后还会做商户身份匹配，这个校验发生在签名校验之后，所以签名没问题也照样被拦下来。

解决：先不要在代码里找毛病，把配置文件的商户号、柜台号和证书里解析出的商户号放一起比对。证书里这些信息可以用keytool命令读取，本地开发机上跑一次就能看到。我的习惯是所有环境的证书文件名里带上商户号后缀，比如merchant-103000000001-test.pfx，从源头杜绝拿错证书。如果多套环境共用一台服务器，certPath配置要按环境分别落盘，不要用同一个目录，避免测试环境把线上证书覆盖掉。

5.2 回调验签一直失败：拼接顺序和空参处理不对

现象：支付流程正常，银行收银台也显示成功了，但notify接口每次验签返回false，订单一直停在未支付状态。

原因：验签时的拼接原文和银行签名时不一致。最常见的有三类：一是拼接顺序不对，某些字段没有按文档顺序排；二是空值字段处理不对，银行侧跳过空字段，商户侧却把空字符串也拼进去了，少拼一个字段和多拼一个空串，最后算出来的摘要完全不同；三是编码不一致，中文参数按UTF-8签名，验签时却按平台默认编码读取。

解决：拿银行回调的原始报文和支付请求的原始报文，用抓包工具导出来逐字段对比。验签前先打印重组后的签名字符串，把空格、换行、空字段都可视化出来看，一般三轮就能定位。稳妥做法是把签名拼接方法独立成工具，支付请求和回调验签共用同一个方法，两边都不会改乱。如果接口文件里明确定义了参数按字典序排列，就按字典序排；没有明确说明时按文档里的字段表顺序排，不要两种混着来。

5.3 同一笔订单被更新两次：异步通知重试与状态机

现象：用户支付成功后，订单的钱不多不少，但订单操作流水里出现两条已支付记录，或者退款时发现订单状态已经是已支付，但关联的支付流水号被后一个通知覆盖。

原因：银行异步通知在未收到成功标志或者网络抖动时会重发，每次通知携带的流水号是同一个，但回调处理没有做幂等保护。第一次通知事务还没提交，第二次通知就闯进来了，两条线程同时看到订单未支付，同时去执行update，最后后提交的覆盖先提交的。

解决：在数据库层面加约束。订单表的支付流水号字段设置唯一索引，更新语句里加状态条件：

update orders set status = 'PAID', pay_seq = ? where order_no = ? and status = 'UNPAID';

只要更新影响行数为1，这笔通知才算处理成功；影响行数为0说明订单已经不是未支付状态，直接返回成功标志并退出。这样无论银行重发几次，重复通知都不会改写业务数据。数据一致性不是靠回调顺序保证的，是靠状态机和唯一约束保证的。接口幂等性这个话题，在支付系统里不是进阶知识，是入门必修课，回调没做幂等的系统，上线第一周就会在交易流水中看到双记录。

5.4 对账不平：只信本地交易表，不信银行对账文件

现象：月底财务对账，本地系统显示100笔已支付订单，银行侧交易明细却是102笔，差额恰好是两笔测试单；或者某笔订单本地显示已支付，但银行对账文件里根本没有。排查代码找不到问题，因为代码没错，问题出在对账口径。

原因：本地订单状态被测试数据、人工修正或者returnUrl误改污染了。凡是跳过银行异步通知手动把订单改成已支付的，统统会在对账文件里暴露出来。对账文件是银行最终清算的依据，它只认银行侧真实成功的交易，本地任何手工操作都改变不了它对不上的结果。

解决：每个工作日定时从银行平台下载对账文件，解析后和本地当日已支付订单做逐笔比对，差异数据进入专门的对账差异表。比对维度至少包含订单号、金额、交易时间、流水号四项，任何一项不一致都要挂起人工处理。测试环境的订单不要和正式环境混在一个库里，否则每天对账都在跟历史脏数据缠斗。这个兜底机制不是可选的，银行接口文档里明确建议商户做对账，实际项目里它就是支付系统最后一个后悔药。

6. 进阶验证：对账文件、幂等设计和上线检查清单

6.1 对账文件解析思路

对账文件一般在银行商户平台下载，也可以通过接口拉取，格式大多是固定分隔符拼接的纯文本，字段顺序在接口文档里有定义。解析时不要手工操作，写一个独立对账模块，按天拉取比对。我的做法是把银行侧数据和本地交易表查出来后在内存里做Map对撞，以订单号为键，比对金额和流水号：

// 伪代码：对账比对核心逻辑 Map<String, BankTxn> bankMap = parseBankFile("20250601.txt"); List<Order> localOrders = orderService.listPaidByDate("2025-06-01"); for (Order o : localOrders) { BankTxn t = bankMap.get(o.getOrderNo()); if (t == null) { diffCollector.add("本地有单，银行无单：" + o.getOrderNo()); } else if (!t.getAmount().equals(o.getAmount())) { diffCollector.add("金额不一致：" + o.getOrderNo()); } }

6.2 幂等状态机

订单状态建议只保留一套状态机：UNPAID、PAID、REFUNDED、CLOSED。回调只允许将UNPAID更新为PAID，退款只允许将PAID更新为REFUNDED，CLOSED是彻底终态。状态流转条件全部在下层方法里做判断，Controller层不写状态相关的业务if else，省得每个接口自己写一套互相冲突的判断逻辑。

6.3 上线检查清单

上线前把这五项过一遍，比反复读接口文档更有用。我自己每次接新的支付渠道，都会先写对账脚本再写支付流程，因为对账脚本会把字段清单逼着先定下来，后面支付代码自然就顺了。希望这个习惯也能帮到你。

本文还有配套的精品资源，点击获取