简介一套完整的农行Web端网银支付Java接口资料包面向需要对接农业银行在线支付能力的Java开发者特别适用于电商平台、在线服务商及企业门户在自有系统中集成网银支付。压缩包共147个文件大小5.1MB文件类型覆盖54个class、19个jar依赖库、34个jsp和28个html页面另有properties配置、cer与truststore证书文件等其中class/jar负责支付核心逻辑与第三方依赖jsp/html提供前端交易示例页面properties和证书则用于环境配置与安全通信。已有2073人学习下载。通过运行附带Demo可快速理解从初始化支付请求、组装交易参数、签名验签到接收银行响应、处理异常以及回调通知的完整流程。资源中的升级版接口包封装了商户配置、参数解析、签名服务、数据验签等实用工具类开发者可直接复用并在此基础上扩展新功能对于需要快速上线农行网银支付的企业而言这份资料能明显缩短对接调研与开发周期。1. 农行web端网银支付Java接口一套文档加demo能不能让你的对接少走两周弯路农行web端网银支付Java接口文件及demo很多人第一眼以为它只是一包接口文档拷贝。实际上这套东西里最有价值的不是PDF而是一个能直接跑起来的Web demo它把农行B2C网银支付从证书加载、报文签名、表单提交到回调验签整条链路串通了。对要接农行网银支付的项目来说省下的是最开始一到两周的摸索时间。适合两类人一是公司要接入农行网银支付、手头只有接口文档没有参考实现的Java工程师二是想研究银行支付网关签名验签逻辑的web端开发。这篇文章我会按自己的拆包习惯把证书、报文、签名顺序、回调处理这些关键点逐个过一遍再把真实对接里最容易翻车的地方列出来。2. 先把接口文档读透证书、报文与签名验签的三层关系拿到这套文件我的习惯不是先开IDE而是先把接口文档从第一页翻到支付流程那一章。农行web端网银支付这类银行接口和互联网公司开放平台最大的差别是报文格式极其固定签名验签规则绕不开证书任何一个字段顺序不对结果就是验签失败或者银行直接拒绝请求。2.1 目录结构与各文件定位解压之后文件一般会按下面几类归堆我习惯把每个文件的功能先在脑子里标一遍文件位置典型文件名用途上线前是否要改文档接口文档PDF、商户接入指南报文定义、URL、字段清单、签名算法说明以农行最新版本为准证书merchant.pfx、bank.cer商户私钥签名、银行公钥验签换正式证书源码PaymentServlet、NotifyServlet支付发起、回调接收demo改造成业务服务工具类SignUtil、MerchantConfig签名验签、配置读取加固依赖库加密jar包农行提供的加解密底层视环境保留如果解压后没有bank.cer只有bank_public_key.txt之类的内容也别急它一般是把Base64形式的公钥文本贴在配置里。核心只有两个商户私钥用来签名银行公钥用来验签。这两个文件对应错了后面所有动作都会失败。2.2 证书体系到底谁签谁验农行B2C网银支付用的是RSA非对称体系。商户在农行申请接入时会拿到一个pfx格式的商户证书这个文件同时包含商户私钥和证书信息访问pfx需要密码密码在申请时自己设置这就是签名用的“私钥”。农行还会提供一份银行公钥cer文件用来验证农行发回来的回调通知确实是农行发出来的。常见误用是把这两个角色搞反。我见过有同事拿着银行公钥去做签名结果提交到网关直接被拒。签名的本质是私有性商户拿自己的私钥给请求报文签名农行用商户公钥验反过来农行拿自己私钥给通知报文签名商户拿银行公钥验。所以商户证书和银行公钥的使用方向恰好相反配置类里这两行注释一定要看清楚。2.3 签名顺序、编码和拼接方式农行接口文档里会给出一个“签名要素”清单。常见做法是把商户号、订单号、金额、币种、返回地址、通知地址等字段按固定顺序拼接成一个字符串再用商户私钥做摘要签名最后Base64编码放进请求报文。这里的顺序不是随便排的农行的验签程序就是按照文档里这个顺序重新拼接一遍再验。这个环节最坑的是两点。第一拼接时要不要带字段名、分隔符是还是空字符串必须和文档里的示例一致多一个空格都会验签失败。第二编码方式要和文档规定一致。农行这类老牌银行网关很多还沿用GBK如果你在拼接签名原串时用UTF-8拿到字节一旦报文里出现中文商品名签名和对端算出来的摘要就永远对不上。测试环境里订单号全是数字可能侥幸通过线上带中文参数就露馅。提示调试验签失败时不要盯着Base64结果看。把签名前那个字符串先打印出来和自己手拼的对比一遍再去确认字符集。绝大多数签名问题出在拼接而不是算法。3. 把demo跑起来从工程导入到回调落库的完整路径这一章说的是实际把农行web端网银支付Java接口demo跑起来的过程。这套demo通常是老式Servlet工程结构不复杂但运行方式和现在流行的Spring Boot不一样环境不对容易卡在第一步。3.1 环境准备与工程导入我先说环境。这种银行demo往往年头不短依赖JDK 1.7或者1.8容器用Tomcat 7或8比较稳。直接拿JDK 11以上跑老工程大概率会遇到JCE加密策略或者xml解析相关的报错倒不是说完全不能修但首次跑通没必要在这上面耗。导入IDE时注意保持工程目录结构别动lib目录下的jar包。农行提供的加密jar包是放在lib里引用的如果你用Maven把它重新整理很容易出现依赖冲突尤其是当本工程里还有公司统一二方库的时候。稳妥做法是先按普通Web工程导入跑通了再考虑迁移。3.2 核心配置项每个参数对应什么demo里一般有一个MerchantConfig类的配置文件可能是properties也可能是硬编码。上线前所有跟商户相关的参数都要换掉。下面这份配置结构是这类demo最常见的款式字段名各家版本略有差别但逻辑一致# 商户号农行分配测试环境和正式环境不一样 merchantId103100000000123 # 商户证书路径pfx格式 merchantCertPath/opt/cert/merchant.pfx # pfx证书密码申请时设置的 merchantCertPwdChangeMe # 农行公钥路径cer格式 bankCertPath/opt/cert/bank.cer # 支付网关地址测试和正式是两套 payGatewayUrlhttps://paygateway.test.example.com/pay # 支付完成后跳转页面地址 returnUrlhttps://www.example.com/pay/return # 异步通知地址农行后台回调 notifyUrlhttps://www.example.com/pay/notify这段配置的要点是商户号、证书路径、网关地址三者是一套对应关系。测试环境必须用农行给的测试商户号和测试证书正式证书在测试环境反而可能报证书无效。returnUrl是用户支付完看到的页面notifyUrl是农行服务端异步通知商户系统的地址通知地址必须是公网可达的HTTPS地址而且不能带端口号中的奇怪参数。3.3 发起支付构造表单的代码逻辑农行web端网银支付的发起方式很传统商户服务器构造一段自动提交的HTML表单让浏览器POST到农行支付网关。demo里一般在PaymentServlet里做这件事。核心代码如下// 支付初始化构造签名原串并输出自动提交表单 protected void doGet(HttpServletRequest req, HttpServletResponse resp) { // 1. 从配置读取商户号与回调地址 String merchantId MerchantConfig.get(merchantId); String orderId req.getParameter(orderId); String amount req.getParameter(amount); // 单位分 String returnUrl MerchantConfig.get(returnUrl); String notifyUrl MerchantConfig.get(notifyUrl); String currency 10; // 人民币 // 2. 按接口文档约定的顺序拼接签名原串 // 字段顺序以农行接口文档为准注释里标明各字段含义 String plain merchantId orderId amount currency returnUrl notifyUrl; // 3. 使用商户私钥签名并做Base64编码 String sign SignUtil.sign(plain, MerchantConfig.get(merchantCertPath), MerchantConfig.get(merchantCertPwd)); // 4. 组装自动提交表单form action指向农行支付网关 String formHtml buildAutoSubmitForm(merchantId, orderId, amount, currency, returnUrl, notifyUrl, sign); resp.setContentType(text/html;charsetGBK); resp.getWriter().write(formHtml); }这段代码里最重要的是第2步的拼接顺序。接口文档里会写清楚先拼哪个字段后拼哪个字段这个顺序必须原样保留不能因为觉得“这样拼更合理”就调整。金额字段注意单位是分而且整个拼接过程完全用字符串不要用double或者float去乘100浮点误差在支付场景里是不能接受的。发起支付这一环还有一个容易被忽略的点form表单的method是POST目标地址是农行网关而不是returnUrl。returnUrl只是农行支付完成之后跳转回商户网站的地址它不承担接收报文的任务。3.4 接收回调验签与幂等处理农行的支付结果通知走的是后台异步通知通知地址就是notifyUrl。这个方法必须能接收POST请求验签通过后更新订单并向农行返回固定的成功标识。demo里的NotifyServlet骨架基本都是这样// 支付结果回调验签 - 更新订单 - 返回成功标记 protected void doPost(HttpServletRequest req, HttpServletResponse resp) { // 1. 按文档约定收集回调字段拼接验签原串 MapString, String params new HashMap(); String signValue req.getParameter(signValue); String signPlain buildPlainText(req); // 与文档签名字段顺序保持一致 // 2. 用农行公钥验签防止伪造通知 boolean passed SignUtil.verify(signPlain, signValue, MerchantConfig.get(bankCertPath)); if (!passed) { resp.getWriter().print(fail); // 验签失败不返回成功标识 return; } // 3. 幂等先查订单状态已支付直接返回成功 String orderId params.get(orderId); if (orderService.isPaid(orderId)) { resp.getWriter().print(SUCCESS); return; } // 4. 落库更新订单附带银行流水号 orderService.markPaid(orderId, params.get(bankSerialNo)); resp.getWriter().print(SUCCESS); }回调处理有三个硬性要求验签必须失败就拒绝返回的响应体只能是农行规定的纯文本成功标识不能返回JSON、不能返回HTML在返回SUCCESS之前业务逻辑必须全部执行完。农行收到这个标识才会认为通知成功如果它超时没收到或者收到的内容不对会按策略重发通知。所以这里不能把待发货这种异步操作提前执行必须在标记支付成功之后后续再触发。3.5 测试环境自测清单在跑通demo之后别急着让农行那边联调先在测试环境把链路走完整。下面是每次接这种支付我都要过一遍的清单检查项通过标准常见失败点证书加载demo启动日志无证书错误pfx密码错、证书路径使用相对路径发起支付浏览器能跳转到农行收银台网关地址配错、签名失败同步跳转支付完成能回跳returnUrlreturnUrl带特殊字符、编码问题异步通知本地能收到POST回调内网穿透失效、notifyUrl未配置公网验签回调验签通过签名原串拼接顺序不一致幂等重复回调不重复发货未加订单状态判断编码中文商品名显示正常请求或回调未用GBK4. 农行web端支付避坑实录证书、编码和回调重复通知的五个现场这一章把我实际见过、自己也踩过的五类问题列出来每一条都按现场现象、根因、解决方法来写。如果你正在联调农行web端网银支付这五条大概率能撞上至少一条。4.1 回调内容全是乱码现象农行异步通知收到的中文参数显示为乱码订单里的商品名完全不可读。原因农行网关按GBK编码发送通知内容而demo工程默认用UTF-8解码。解决在接收回调的Servlet入口处调用req.setCharacterEncoding(GBK)读取参数后再做业务处理。如果用了框架还需要检查框架的编码过滤器防止它先按UTF-8把参数解析掉。4.2 验签永远失败现象发起支付时农行返回验签失败日志里只给出一个模糊的错误码。原因最常见的是签名原串拼接顺序和接口文档不一致其次是拼接的字符串编码不是GBK或者拼接时带了不可见字符。解决把demo里拼接签名原串的代码和接口文档的示例报文逐字符核对尤其在订单号后面检查有没有多余空格。我自己调试时习惯把拼接后的字符串打印出来用十六进制查看尾部是否藏着换行符。4.3 支付成功但订单没入账现象用户在农行收银台支付成功商户后台订单状态还是待支付。原因异步通知处理代码里业务异常或者响应内容不是农行规定的成功标识。很多人在回调Servlet里返回了JSON格式的{code:200}农行不认这个结果会判定通知失败并重发。解决回调方法的返回内容仅允许农行文档指定的纯文本成功标识比如SUCCESS。如果业务处理抛异常也要捕获后在finally位置输出成功标识确保订单状态不会被漏更。4.4 重复回调导致重复发货现象同一笔订单收到多次通知后台记录里出现两条发货记录。原因农行在没收到成功确认或网络超时的情况下会重发通知如果没有做幂等处理同一个orderId会被处理两次。解决在更新订单的SQL里加状态条件比如UPDATE orders SET statusPAID WHERE order_id? AND statusUNPAID更新行数为0说明之前已经处理过。demo里那一段isPaid判断是必须保留的不能因为“现在农行重发没那么频繁”就删掉。4.5 新JDK环境跑demo报算法异常现象工程在JDK 8下正常换到JDK 11报InvalidKeyException或NoSuchAlgorithmException。原因老demo里可能硬编码了旧的算法名或者JCE的默认策略在新版本里发生了变化。解决先看异常堆栈里的算法名和接口文档对比改成文档支持的标准写法。如果只是跑demo验证逻辑最省事的方式是换回JDK 8配Tomcat 8让环境和demo的年代匹配业务侧再考虑升级问题。提示第4.2和4.4这两条既影响接口联调也影响生产安全建议代码Review时作为必查项。支付回调的幂等不是可选项。5. 把demo改造成能上线的支付模块三个值得先做的重构动作demo跑通只是开始直接拿demo打生产包会留下不少隐患。我的做法是抽出下面这三个重构动作每接一次银行支付都先做完再谈联调。第一个动作是把支付逻辑从Servlet里挪到一个独立的Service类。Servlet是Web层不该写签名、拼报文的逻辑。我会定义这样一个接口让controller只做参数接收和视图返回public interface PayService { // 创建支付表单返回自动提交HTML String createPayForm(PayOrder order); // 处理异步通知返回农行要求的应答文本 String handleNotify(PayNotify notify); }实现类里放证书加载、签名原串拼接、验签和幂等判断。这样写的好处是单元测试能直接调Service验证签名逻辑不必启动Tomcat。第二个动作是把证书密码和网关地址从代码里挪出去放到配置中心或者环境变量里。农行证书密码放在代码仓库里是安全隐患而且换证书时还得重新发版。我一般用环境变量注入密码配置项只保留路径。第三个动作是加一个主动查询订单状态的兜底定时任务。支付回调可能在极端情况下丢失农行提供的订单查询接口就是为这个准备的。定时任务每天扫描超过N小时仍处于待支付状态的本地订单调用查询接口确认银行侧状态再做补单处理。这不是多余工作量银行接口偶尔就是会让人体验一下“玄学”。从那以后我每次接银行支付都会强制自己先走完这三个动作再进入联调窗口回调幂等和主动查单这两件事绝不在上线前夜补。一次支付回调丢失引发的工单远比写这几行代码耗时。希望帮到你。本文还有配套的精品资源点击获取