农行BRIDGE商户直连Java V1.4 Demo接入与避坑指南

简介这份资源是中国农业银行缴费中心BRIDGE新版商户直连的Java版DEMOV1.4面向需要接入农行缴费支付接口的商户研发与系统集成人员。DEMO覆盖订单处理、支付确认、退款及回调通知等核心交易环节并附有对应版本的接口文档便于开发者理解接口规范并快速落地到自身业务系统。资源包共133个文件以Java源码、JSP页面及少量JAR依赖为主另有XML配置、JS脚本、证书文件及PDF说明文档等整体大小约6.92MB结构清晰适合具备Java基础、正在做银行支付对接的中级开发者参考。目前已有566人学习下载。通过阅读源码和文档可掌握农行API调用、支付请求组装、响应解析及证书配置等关键环节有助于缩短联调周期并提升支付模块的稳定性。1. BRIDGE 商户直连先分清它和页面跳转模式再看 JAVA DEMO 值不值得跑做收费系统接入的同学应该都见过这个场景学校要收学费物业要收管理费甲方要求在自家公众号或 App 里完成支付不让用户跳到银行页面再跳回来。农行缴费中心为此提供了两种商户接入方式一种是页面跳转模式用户被重定向到农行缴费页另一种就是标题里的 BRIDGE 商户直连——商户自己的系统直接调农行的下单、查询、退款、对账接口支付页仍然由商户自己控制。JAVA 版本的 V1.4 Demo 是农行配套的样例工程代码加文档把报文、签名、回调整条链路的落地方式都写清楚了。下面就把三件事讲清楚BRIDGE 直连是什么、V1.4 的 JAVA Demo 怎么跑通、以及上线前在哪儿会翻车。2. BRIDGE 直连的两块基石XML 报文怎么拼RSA 签名怎么验2.1 报文为什么是 XML字段构成与交易码农行缴费中心 BRIDGE 直连走的协议是 HTTPS POST请求和响应体都是 XML。我第一次接的时候也问过为什么还在用 XML换 JSON 不好吗。看过文档后理解了这个接口面向上千家收费单位很多单位的系统用 Java、.NET甚至还有跑在小型机上的老系统把报文定成 XML 加固定字段所有语言都能解析。所以 V1.4 的 JAVA Demo 里XmlUtil 承担了几乎所有报文组装和解析工作这个类不要轻易动更不要图省事改成 JSON 再自拼。一个典型的商户直连下单请求长这样字段以 V1.4 文档为准结构是一致的?xml version1.0 encodingUTF-8? Request TransCode下单交易码/TransCode MerchantNo商户号签约后由缴费中心分配/MerchantNo OrderNo商户系统生成的订单号整个平台唯一/OrderNo OrderAmount10000/OrderAmount PayType01/PayType NoticeUrlhttps://your-domain.com/pay/notice/NoticeUrl ReturnUrlhttps://your-domain.com/pay/return/ReturnUrl /Request这里的 OrderAmount 是字符串单位是分。10000 表示 100 元整。文档会把这条写在最显眼的位置但很多新同学还是习惯用 double 传金额结果网关要么报格式错误要么因为浮点精度丢了一分钱。在你自己系统的数据库里订单金额也建议用 BIGINT 存分或者 VARCHAR 存字符串总之不要让浮点数出现在金额链路上。TransCode 是交易码用来告诉网关你要做哪类交易。BRIDGE 直连常用到的交易码就那几个下单、单笔查询、退款、对账文件下载。JAVA Demo 的 Constants 类里会把这些交易码定义成常量和文档里的交易码说明一一对应。有的版本在直连模式下还要求带签名时间、随机数这类字段具体以你拿到的 V1.4 文档清单为准。这些字段虽然不参与业务判断但参与签名所以看到表里有就不要漏。提示不要把 Demo 里定义好的交易码抄到生产环境就不再回看。农行升级接口版本时交易码一般不变但新增字段是常态接 V1.4 时把文档里的字段清单和 Demo 的 Constants 逐行对一遍能省掉后面很多排查时间。2.2 RSA 签名与验签SignedMsg 是怎么算出来的报文本身不加密签名才是身份和完整性的保证。BRIDGE 直连的规则可以理解为双向签名商户用自己的私钥对请求报文的关键字段签名网关用商户的公钥验签网关返回的报文和异步回调报文则用农行的私钥签名商户这边拿农行公钥验签。两头都是 RSA但 Demo 里是两套方法、两个证书对象别搞混。我把这个关系记成一句话上行验商户下行验农行。这里最关键的一点是签名不是把整段 XML 拿去算。而是先把报文里的字段按文档指定的顺序拼成一个明文串再对这个明文串做 SHA256withRSA最后 Base64 编码放到 SignedMsg 字段里。所以整个链路其实是“拼串 → 签名 → 组装 XML → 发送”拼串在前签名在后。JAVA Demo 的 RSAUtil.sign 方法接收的是拼好的明文串不是 XML 字符串。private static final String SIGN_ALGORITHM SHA256withRSA; public static String sign(String plainText, PrivateKey privateKey) throws Exception { Signature signature Signature.getInstance(SIGN_ALGORITHM); signature.initSign(privateKey); signature.update(plainText.getBytes(StandardCharsets.UTF_8)); return Base64.getEncoder().encodeToString(signature.sign()); }拼接顺序由文档里一张表定义例如 TransCode、MerchantNo、OrderNo、OrderAmount 按固定顺序接在一起中间不加分隔符。Demo 的 XmlUtil.buildSignedString 封装的就是这个逻辑——它负责拼明文串sign 负责做 RSA两者职责不同。如果只换其中任何一个网关都会回验签失败。现场排错时我见过同事把整个 XML 报文丢给 sign网关永远回“验签失败”这就是没理清这两层的典型例子。验签方向要单独强调。下行报文和回调通知用的字段集合不同拼接规则也不同。V1.4 文档对异步通知有一节单独的签名说明Demo 里对应 verifyNotice 这样的方法字段清单比下单响应多了支付时间、平台流水号等。用下单的 buildSignedString 去拼通知字段必然验签不过。农行公钥来自商户入驻时提供的一个 .cer 文件Demo 一般放在 cert 目录下上线时记得和测试公钥区分开。2.3 配置文件证书、商户号、网关地址各就各位JAVA Demo 的配置集中在一个 properties 文件里这比有些银行把配置写死在代码里要规矩得多。V1.4 的 Demo 配置项通常长这样merchant.no000000000000 merchant.cert.path/config/certs/merchant.pfx merchant.cert.password证书密码 abc.public.cert.path/config/certs/abc_public.cer gateway.urlhttps://test-gateway.example.com/gateway四个配置项分别对应四件事merchant.no 是签约后分配的商户号相当于你在缴费中心的身份证merchant.cert.path 和 password 是商户私钥证书格式一般是 pfxPKCS12abc.public.cert.path 是农行公钥文件用来验签下行报文和回调gateway.url 是网关地址测试环境和生产环境完全不同。我第一次在生产切包时就是把前三个都换成了生产唯独网关地址漏了一条结果整个上午都在排查“为什么测试通生产不通”后来才发现是 URL 没切。有些同学会问既然有商户证书为什么还要单独一个农行公钥文件。这是 BRIDGE 直连和不少第三方支付平台的差异点第三方支付通常只给你一套商户私钥和平台公钥农行这里把商户证书和农行公钥分开管理对应的是前面说的“双向验签”。所以 cert 目录下至少有两个文件缺了 abc_public.cer验签回调时就会直接报找不到证书。到这里报文结构、签名算法、配置位置这三件事都立住了下面动手把 Demo 跑起来。3. Java 版 V1.4 Demo 跑通第一笔下单导入、配置与核心调用3.1 导入工程先看目录结构和依赖拿到 V1.4 的 JAVA Demo 压缩包解压后目录大概是这样的src/main/java 放源码conf 或 resources 放配置和证书doc 放接口文档和 Demo 说明lib 下放依赖 jar如果不走 Maven。把工程导入 IDEA 或 EclipseMaven 工程直接按 pom 导入纯 lib 版就把 lib 下的 jar 全部加到项目里。依赖通常就三样HTTP 客户端HttpClient 或 JDK 原生 HttpURLConnection、XML 解析库Dom4j 或 JDK 的 DocumentBuilder、Base64 工具commons-codec 或 java.util.Base64。导入后第一件事不是跑而是确认 JDK 版本和 java 环境变量配置。V1.4 的 JAVA Demo 一般兼容 JDK 1.8如果本机装的是 JDK 17老版本里个别依赖 sun.misc 包的写法会直接报编译错误。不过 V1.4 的常见版本用的是 java.util.Base64JDK 8 就能跑。如果启动时报 ClassNotFound先看是不是 lib 没引全如果报编译错误优先怀疑是本机 JDK 版本和 Demo 要求的版本不一致。这一步花十分钟检查比后面在业务代码里排错划算得多。3.2 配置商户参数三个必改项和一个必查项在跑通之前把 config.properties 里以下四项过一遍merchant.no换成申请到的测试商户号别用 Demo 里自带的占位值。merchant.cert.path换成你的 pfx 证书绝对路径。相对路径在 IDE 里跑没问题打成 jar 后就容易出问题所以直接写绝对路径最稳。merchant.cert.password证书密码注意不是登录密码。有同学把网银登录密码当成证书密码填进去加载时报 password incorrect。abc.public.cert.path必查项确认文件是不是文档配套的农行公钥。有的 Demo 压缩包自带一个测试公钥跑测试环境没问题切生产前必须替换。改完配置写一个最简 main 方法或者直接跑 Demo 自带的下单示例类。只要能拿到一个 PayUrl说明基本链路已经通了。如果这一步就报错按 5.1 的证书检查顺序去看先排除证书问题再碰业务代码。3.3 跑通下单接口代码级走查与参数说明下单是 BRIDGE 直连最核心的一步后面的查询、退款都复用同一套“组参、拼串、签名、POST、解析”的模式。下面这段是参照 V1.4 JAVA Demo 的常见写法整理的下单主流程和你拿到的 Demo 类名可能不完全一样但步骤是同一个骨架// 1. 准备订单参数 String orderNo 20250612001; // 商户订单号全局唯一 String amount 10000; // 金额单位是分 String payType 01; // 支付方式01 为聚合支付 // 2. 组装请求参数顺序与文档签名规则保持一致 MapString, String params new LinkedHashMap(); params.put(TransCode, Constants.TRANS_ORDER); params.put(MerchantNo, Config.getMerchantNo()); params.put(OrderNo, orderNo); params.put(OrderAmount, amount); params.put(PayType, payType); params.put(NoticeUrl, https://your-domain.com/pay/notice); params.put(ReturnUrl, https://your-domain.com/pay/return); // 3. 拼签名串并签名顺序错了网关一定验签失败 String signData XmlUtil.buildSignedString(params); String signedMsg RSAUtil.sign(signData, Config.getPrivateKey()); params.put(SignedMsg, signedMsg); // 4. 把参数转成 XML 并 POST 到网关 String requestXml XmlUtil.mapToXml(params); String responseXml HttpUtil.post(Config.getGatewayUrl(), requestXml); // 5. 解析响应ReturnCode 为 000000 表示下单成功 MapString, String response XmlUtil.xmlToMap(responseXml); if (000000.equals(response.get(ReturnCode))) { String payUrl response.get(PayUrl); // 把用户重定向到 payUrl或按文档生成自动提交表单 }这段代码里有几个细节值得停下来看。第二步用 LinkedHashMap 而不是 HashMap因为 HashMap 不保证遍历顺序而拼签名串严格要求字段顺序。有些版本用 TreeMap 按字典序排本质是一样的顺序必须和文档定义的签名规则一致。第三步里 buildSignedString 和 sign 是两个动作前者拼明文后者做 RSA改任何一个都会导致网关验签不通过。如果你不想用 Demo 的 buildSignedString自己拼也行但两个边界必须踩对第一字段值为空时要拼空串不是跳过这个字段第二V1.4 新增的扩展字段如果文档说参与签名位置要按文档放不能随手插到末尾。这两个边界几乎覆盖了所有“为什么我照着文档写还是验签失败”的问题。下单成功拿到 PayUrl 后把用户重定向到农行收银台用户完成支付后农行会同步跳回 ReturnUrl同时异步往 NoticeUrl 推一个通知报文。到这里第一笔 BRIDGE 直连交易就算跑通了。后面章节的查询、退款、对账都是在“能下单成功”这个前提下继续扩展的。4. 查询、退款与对账下载把直连接口用完整的三个动作4.1 单笔查询轮询节奏与状态码映射商户接直连几乎都要做“订单状态查询”因为用户支付完可能直接关了浏览器回调通知没送到订单就一直挂起。BRIDGE 直连提供了单笔查询接口商户拿着订单号随时能查。参数比下单少很多TransCode、MerchantNo、OrderNo个别场景还要带缴费中心返回的平台流水号。Demo 里查询方法的骨架和下单几乎一模一样区别只在交易码和返回字段。查询接口不要太“勤奋”。我见过有同学写了一个每 5 秒轮询所有未支付订单的定时任务上线第二天就被网关限流。常规做法是用户在前端点“刷新状态”时主动查一次后台对创建超过 5 分钟仍未支付的订单每小时补一轮。查询结果的返回字段里最重要的是订单状态和实付金额。状态码在 V1.4 文档里有一张映射表Demo 里通常也做了枚举解析但状态码到你本地订单状态机的对应关系需要自己维护。比如你本地有“待支付”“支付中”“已关闭”三个状态银行返回的“已支付”要能正确落到你的状态机上。4.2 退款部分退、全额退和多次退的边界缴费场景里退款比电商更常见学生退学、物业费多收、用户重复缴费。BRIDGE 直连的退款接口在 Demo 里有完整示例核心参数是原订单号、退款金额、商户退款订单号MapString, String params new LinkedHashMap(); params.put(TransCode, Constants.TRANS_REFUND); params.put(MerchantNo, Config.getMerchantNo()); params.put(OrderNo, originalOrderNo); // 原商户订单号必须对应一笔已支付订单 params.put(RefundOrderNo, refundOrderNo); // 商户退款订单号全局唯一 params.put(RefundAmount, 5000); // 退款金额单位分不能超过可退金额 // 后面同样走拼签名、POST、解析结果退款接口有三个边界V1.4 文档里都写了但容易在实际开发中被忽略。第一部分退可以多次每次的 RefundOrderNo 不能重复第二退款接口返回“受理成功”不代表钱已到账退款是异步的最终结果要靠查询或回调确认第三如果原订单已跨过资金清算节点退款可能长时间停在“处理中”需要人工关注。我一般会单独建一张退款流水表申请退款时写一条然后用定时任务查询退款状态对超过 T1 还停在处理中的记录告警。V1.4 的 Demo 没有这部分但生产系统必须有。4.3 对账文件T1 下载与解析对账跟查询是两条并行的路子。BRIDGE 直连的对账文件是 T1 生成的农行侧每天凌晨把前一天的交易汇总成文件商户通过接口主动下载。单笔查询解决的是“单个订单到底成没成”对账文件解决的是“昨天全量交易和本地系统是否一致”两者缺一不可。对账文件下载接口的参数主要是交易码、商户号、文件日期返回的是文件内容或下载地址具体看版本。下载下来的对账文件常见格式是每行一条交易字段之间用竖线分隔文件头和文件尾各有一行汇总。解析代码骨架如下String filePath /tmp/check_20250611.txt; try (BufferedReader reader Files.newBufferedReader( Paths.get(filePath), StandardCharsets.UTF_8)) { String line reader.readLine(); // 去掉 UTF-8 BOM否则第一行第一列会带不可见前缀 if (line ! null line.startsWith(\uFEFF)) { line line.substring(1); } while (line ! null) { // 跳过文件头和文件尾的汇总行 if (line.startsWith(H) || line.startsWith(T)) { line reader.readLine(); continue; } String[] cols line.split(\\|, -1); String orderNo cols[1]; // 订单号 String amount cols[2]; // 金额单位分 String status cols[3]; // 交易状态 reconcile(orderNo, amount, status); line reader.readLine(); } }对账文件解析的两个高频坑一个在编码一个在分隔符。编码上如果文件是 GBK 而你按 UTF-8 读中文字段会乱码如果文件带 UTF-8 BOM 而你没过滤第一行第一列会解析出脏字符。分隔符上有的版本用竖线有的用逗号列的顺序也可能和文档描述不一致。V1.4 的 Demo 里带了解析示例先按它的分隔符跑一遍再决定要不要改成更通用的解析方式。对账的核心动作是把对账文件里的订单号和金额跟本地订单表做 LEFT JOIN找出两类差异本地有、银行没有的叫单边账要发起退款或原因排查银行有、本地没有的叫掉单要补登记。这个核对逻辑每家商户自己写Demo 不会替你完成但它决定了 BRIDGE 直连上线后的财务对账效率。对账单入库后我习惯每天跑一条差异 SQL连续三天为零才算这一阶段收尾。5. BRIDGE 直连避坑JAVA 版五个高频踩坑点这一章把我在 BRIDGE 直连对接中真正踩过的坑以及帮别人排过的坑按出现频次排个序。每一条都是现象、原因、解决三步可以直接拿来对着排查。5.1 坑一证书加载失败报“Invalid keystore format”现象程序一启动加载商户证书就抛 IOException提示 Invalid keystore format或者 KeyStoreException 提示 Unrecognized keystore。原因农行发的商户证书是 PKCS12 格式扩展名一般是 .pfx。不少同学习惯按 JKS 的写法加载KeyStore.getInstance(JKS)。JKS 和 PKCS12 内部结构完全不同用 JKS 去读 pfx 读不动自然报格式错误。还有一种情况是证书密码填错把商户登录密码或网银密码当成证书密码加载时一样报错。解决显式指定 KeyStore 类型为 PKCS12。加载代码按下面这段替换可以绕开绝大多数证书问题KeyStore keyStore KeyStore.getInstance(PKCS12); try (InputStream in new FileInputStream(certPath)) { keyStore.load(in, certPassword.toCharArray()); } PrivateKey privateKey (PrivateKey) keyStore.getKey( keyStore.aliases().nextElement(), certPassword.toCharArray());补充一个快速判断方法在命令行用 keytool -list -storetype PKCS12 -keystore merchant.pfx 看能不能列出证书条目。能列出说明文件是 PKCS12问题出在代码列不出先怀疑文件本身是不是被改过格式。5.2 坑二回调通知验签失败现象下单和支付都正常异步通知也收到了但用 Demo 的验签方法一验就不通过。很玄学的是同样的代码验下单响应没问题到通知就挂了。原因通知报文比下单响应多了好几个字段比如支付时间、平台流水号、用户标识。这些多出来的字段在文档的“异步通知签名规则”里有单独的字段顺序很多同学以为所有接口共用同一套拼串规则拿下单的 buildSignedString 去拼通知的字段漏字段或错顺序验签必然失败。解决按 V1.4 文档对异步通知的专门说明把通知里的每个字段都纳入拼接包括值为空的字段。Demo 里对应 verifyNotice 这类方法直接复用它不要自己另写一套。验签成功之后再更新订单状态验签失败时把通知原文记录下来人工处理。这个环节绝对不能跳过验签回调地址一旦泄露伪造通知会直接导致订单状态被篡改。5.3 坑三商户名、商品名乱码银行侧显示问号现象下单成功后在农行收银台看到商户名称是乱码或问号订单详情里商品名也不正常。原因两端编码不一致。商户系统发送请求时 XML 头声明 UTF-8但 HTTP 客户端读响应、发请求使用了默认字符集比如 Windows 下的 GBK或者文档里某个字段明确要求 GBK而 Demo 全局写的是 UTF-8没注意到字段备注。解决全程把编码钉在 UTF-8。发送时用 StandardCharsets.UTF_8 取字节流读取响应时同样显式指定 UTF_8不要用 response.body().string() 这类隐含转码的写法。如果文档明确某个字段要求 GBK单独对那一个字段做转码不要全局切换。排查时可以打印请求 XML 的字节流能快速确认是发送端还是接收端转错。5.4 坑四测试环境全通切生产全是“商户不存在”现象测试环境跑了两周都正常把配置换成生产参数后下单接口立刻返回“商户不存在”或“无权限访问”。原因三个最容易漏的生产配置——网关地址还指向测试地址、生产商户号和测试商户号不一致、证书还是测试签发的证书。还有一个隐藏点生产网关对调用方 IP 做了白名单服务器换了出口 IP 没提加白报错表现很像“商户不存在”。解决切生产环境时按清单逐项核对网关地址、商户号、证书文件三个必须一起换。白名单至少提前一个工作日提交给银行侧。有些银行支持多出口 IP如果服务器同时走多条线路记得把每个出口 IP 都提上去。为了避免这种低级事故我现在所有渠道的对接都强制要求配置文件和部署包分离测试环境和生产环境使用不同 profile切换时 grep 一遍 jar 包里的 gateway.url 和 merchant.no确认没有测试值残留。5.5 坑五对账文件金额对不上差几分钱现象对账文件解析完所有订单金额加总跟本地订单表加总差了几分钱翻来覆去找不到哪一笔不对。原因金额精度或解析边界处理不当。一种是本地订单表用 double 存金额浮点累加出现误差另一种是对账文件里“退款金额”是单独一列你把它当成普通交易金额也累加了还有一种是文件带 BOM 头第一行第一列多了一个不可见字符导致那笔金额解析出来多了位。解决金额一律用整数分或 BigDecimal不要在金额链路上出现 double。解析文件第一行先做 BOM 过滤。退款金额按文档注释单独累加。对完账发现差异时先写一条 SQL 把金额不一致的订单拉出来看是不是解析问题再核对文件行数和本地订单数差一行就逐行对比通常很快定位。如果你刚接 BRIDGE这五个坑至少会踩到两个提前对照检查一遍能省出一天的血泪排查时间。6. 把 Demo 改造成能上线的服务版本差异、自检与验证6.1 V1.4 相比旧版本优先核对三处差异如果你是从 V1.3 或更早版本升上来的重点核对三处字段清单是否有新增扩展字段签名规则是否把新增字段纳入拼串对账文件格式是否增加了列。V1.4 的 Demo 里这些变化通常直接体现在 Constants 类、XmlUtil 和解析示例类中。最稳妥的办法是把新旧两版文档里的“报文节点说明”表格逐行 diff 一遍而不是只看升级说明的摘要。6.2 上线前的自检清单我把每次接直连的自检动作整理成了一张表照着过一遍基本能挡住绝大多数低级事故检查项操作通过标准JDK 与工程编译、启动无报错Demo 自带示例可以正常启动证书keytool -list 验证 pfx能列出证书条目密码正确配置核对生产配置网关地址、商户号、证书三项与生产一致下单下一笔 1 分钱订单返回 PayUrl可跳转收银台回调本地伪造通知验签正常报文通过篡改报文不通过退款对已支付订单全额退款返回受理成功T1 内到账对账下载前一日对账文件文件行数与本地订单数一致6.3 一个验证惯用技巧本地伪造回调报文做回归最后留一个我个人很常用的验证手段。第一次接渠道时把真实环境收到的一两个回调报文保存成文本文件放到测试资源目录里。以后每次改代码、升版本跑一遍“原报文验签必须通过、改一个字段的报文验签必须失败”的断言。操作上可以在 JUnit 里直接读文本文件调用验签方法也可以起一个本地 HTTP 端口用 curl 模拟银行向它 POST 通知报文curl -X POST http://localhost:8080/pay/notice -H Content-Type: text/xml --data-binary notice_sample.xml这个方法验证的是三条链路公钥文件有没有放对、拼接规则有没有改坏、解析逻辑有没有被代码重构影响。比依赖银行在测试环境给你推一单真实回调要快得多。我每接一个渠道都会保留几份真实报文作为回归用例V1.4 升级后跑一次回归几分钟就能确认这版代码没有破坏验签逻辑。这个习惯救过我很多次在版本升级时比翻文档可靠。希望帮到你。本文还有配套的精品资源点击获取