农行缴费中心BRIDGE商户直连DEMO对接指南：从本地跑通到生产避坑

简介：面向中国农业银行缴费中心BRIDGE新版商户直连场景的Java版DEMO（V1.4），专为需要接入农行在线支付能力的商户或后端开发者设计，解决从接口调用、订单处理到支付回调的全流程对接问题。资源包共133个文件，约6.92MB，核心为57个Java源码与44个JSP页面，并配套14个jar依赖、5个XML配置、2个证书文件及PDF/TXT说明文档；其中Java源码承担交易逻辑，JSP页面供本地联调测试，jar包提供基础依赖，证书用于安全通信。目前已有567人学习下载，适合具备Java基础、正在对接农行缴费接口的开发者参考。通过示例代码可快速掌握下单、支付确认、退款处理及回调通知等关键业务；V1.4接口文档详细说明了请求参数、响应格式与错误码，配合JSP页面与本地证书可完整模拟从发起支付到接收结果的流程，从而有效缩短商户系统与农行的对接周期。

1. BRIDGE商户直连这套DEMO，到底在解决谁的问题

拿到“中国农业银行缴费中心-BRIDGE新版商户直连DEMO-JAVA版本（V1.4）及文档”这套东西的Java工程师，多半带着两个问题：BRIDGE到底怎么对接，这份DEMO能不能改改就上生产。我的结论先说在前面：它不能直接上生产，但它是接触缴费中心“商户直连”链路时最该先看懂的一份参考实现。

做缴费对接最贵的不是服务器，而是“猜”。接口文档写得再细，签名串顺序、回调应答格式、金额单位，总有几处要拿真实报文去试。DEMO的价值就是把“猜”变成“改”：换上自己的商户号、证书路径、回调地址，在本地跑通一笔缴费请求，后面联调和生产部署的坑才看得见摸得着。

这套东西适合三类人：第一次对接农行缴费中心的后端开发，要在已有系统里嵌进缴费能力的架构师，以及负责回调通知联调的中级Java工程师。下面按“看时序、跑DEMO、调参数、踩坑、上生产”的顺序展开，新手可以一步步跟着复现，熟手可以直接跳到第4章和第5章看参数与避坑。

2. 拿到DEMO包先别急着跑：先看懂BRIDGE的对接路径

2.1 间连与直连的差别：为什么农行要单独开放一套BRIDGE

缴费业务里常见的接入方式是间连，也就是商户把支付请求交给自己签约的收单机构或渠道方，由渠道方再转发给银行。这种方式好处是商户对接简单，但坏处也明显：报文协议跟着渠道方走，渠道方的处理逻辑像黑匣子，出了问题商户只能等渠道反馈，连原始报文都未必拿得到。

农行缴费中心这套BRIDGE商户直连，走的是另一条路。商户系统直接和缴费中心对接，中间不再隔一层渠道。商户自己控制报文拼装、签名、通知应答和重试策略，订单状态在哪里断的、哪笔报文验签失败，全都能在自己的日志里看到。代价也很直接：加密证书、签名串顺序、回调防重、对账文件解析，这些事情全要商户系统自己扛。

所以BRIDGE这套DEMO真正的角色，是缴费中心对外开放的桥接通道的参考实现。它把“商户侧该做的事情”做成了一个能跑的Java工程，而不是只丢给你一本接口文档。理解这一点，再看包里那些类，就不会觉得目录结构乱。

2.2 DEMO包的目录结构与运行入口

解压后一般是一个标准的Maven工程，包名里通常带有abchina或者bridge字样。我见过的这类DEMO，大体上分四块：核心工具、业务服务、配置文件和文档。用tree看一下结构：

$ unzip BRIDGE-DEMO-JAVA-V1.4.zip $ cd bridge-demo $ tree -L 3 -I target . ├── pom.xml ├── src │ ├── main │ │ ├── java │ │ │ └── com/abchina/bridge/demo │ │ │ ├── BridgeDemoApplication.java │ │ │ ├── core │ │ │ │ ├── config/BridgeConfig.java │ │ │ │ ├── crypto/SignUtil.java │ │ │ │ └── http/HttpClientUtil.java │ │ │ └── service │ │ │ ├── PayOrderService.java │ │ │ └── NotifyReceiver.java │ │ └── resources │ │ ├── application.properties │ │ ├── merchant_private_key.pem │ │ └── platform_public_key.pem │ └── test/java/com/abchina/bridge/demo/SignTest.java └── doc ├── 接口文档V1.4.pdf └── 商户接入指南.pdf

第一次接触这套代码，先看三个文件就够了：BridgeConfig.java是配置加载入口，SignUtil.java是签名和验签实现，application.properties里是所有需要替换的参数。那个BridgeDemoApplication.java是启动入口，本地可以通过IDE直接跑main方法，也可以打成jar包执行。

这里要提醒一句：目录里的merchant_private_key.pem和platform_public_key.pem在DEMO包里放的是示例密钥，绝对不要直接拿它上生产。V1.4文档里会明确告知商户开发环境和生产环境的密钥获取方式，通常是在商户服务平台上申请下载。

2.3 一笔缴费从发起到对账的完整时序

跑DEMO之前，建议先把整个链路的时序画在脑子里。BRIDGE商户直连的缴费流程，我一般会拆成六个步骤：

1. 商户在缴费中心完成报备注册，拿到商户号、应用AppId和签名密钥。
2. 用户在商户系统发起缴费，商户后端生成订单号、缴费金额和缴费项目编码。
3. 商户系统把这些参数按约定拼好，用商户私钥签名，把报文POST到BRIDGE下单接口。
4. BRIDGE同步返回受理结果。注意这个返回只代表银行侧“收到并受理”，不等于缴费成功。
5. 银行侧完成后续处理，通过异步通知把最终缴费结果推送到商户的回调地址。
6. 商户日终下载对账文件，与本地订单逐笔核对。

很多第一次对接的同学在第三步就把同步返回当成最终结果处理，这是最容易翻车的地方。同步返回里的订单状态只代表受理状态，可能是待支付、处理中这一类中间态。真正的成功或失败要以异步通知为准，最终以对账文件为准。

3. 本地跑通BRIDGE商户直连DEMO：三步完成

3.1 环境准备：JDK 1.8、Maven与环境变量

这套DEMO基于Java开发，本地环境需要JDK和Maven。网上搜java环境变量配置详细教程能搜出一大堆，这里只说和这个DEMO有关的两个关键点。

第一，JDK版本建议用1.8或11，不要一上来就上17。原因很实际：DEMO包的pom.xml里依赖的编译参数和部分库版本，可能没有在更高版本JDK下验证过。我见过有人用JDK 17直接编译，报了一堆“illegal reflective access”的警告，虽然不一定致命，但会让新手分不清是环境问题还是代码问题。

第二，JAVA_HOME和MAVEN_HOME要配到用户级环境变量里，不要在IDE里面单独指定。因为后面打jar包、写脚本跑对账任务时，命令行里还需要用到这两个变量。

下面是Linux/macOS下的配置示例，Windows下把export换成set即可：

# Linux / macOS export JAVA_HOME=/usr/local/jdk1.8.0_202 export MAVEN_HOME=/usr/local/apache-maven-3.6.3 export PATH=$JAVA_HOME/bin:$MAVEN_HOME/bin:$PATH # 验证 java -version mvn -version

配置完成后，进入DEMO根目录编译打包。Maven第一次执行会下载依赖，如果公司内网有Nexus私服，记得在settings.xml里配置mirror，否则会卡在下载阶段很久。

$ cd bridge-demo $ mvn clean package -DskipTests $ java -jar target/bridge-demo-1.4.jar

如果启动失败，先别急着去翻代码。九成是三个原因：JAVA_HOME没配对导致找不到java命令；8080端口被占；配置文件里的路径写错导致读取不到密钥文件。端口问题在application.properties里改server.port即可，不需要动代码。

3.2 配置加载与发起第一笔缴费请求

跑通的第一件事是把application.properties里的参数换成本地可用的值。这个配置文件是核心，字段不算多，但每个都关系到链路是否能走通：

配置加载的代码在BridgeConfig.java里，它的核心逻辑就是读取配置文件、校验必填项、把PEM文件加载成密钥对象。注意看代码里对路径的处理：

public class BridgeConfig { private String merchantNo; private String appId; private PrivateKey merchantPrivateKey; private PublicKey platformPublicKey; private String gatewayUrl; private String notifyUrl; public static BridgeConfig load(Properties props) { // 必填项校验：这里不要放过空值 if (props.getProperty("bridge.merchantNo") == null || props.getProperty("bridge.merchantNo").trim().isEmpty()) { throw new IllegalArgumentException("商户号不能为空，检查application.properties"); } BridgeConfig config = new BridgeConfig(); config.merchantNo = props.getProperty("bridge.merchantNo").trim(); config.gatewayUrl = props.getProperty("bridge.gatewayUrl").trim(); config.notifyUrl = props.getProperty("bridge.notifyUrl").trim(); // 密钥加载失败时，异常要往上抛，不要在catch里吞掉 config.merchantPrivateKey = PemUtil.loadPrivateKey( props.getProperty("bridge.privateKeyPath")); config.platformPublicKey = PemUtil.loadPublicKey( props.getProperty("bridge.platformPublicKeyPath")); return config; } }

逻辑说明：这个类做的事情很直白，但有两个细节值得模仿。一是在加载配置时做必填校验，而不是等到发请求时才报空指针，这能让配置错误提前暴露。二是密钥加载失败时直接抛异常，这样启动阶段就能看到问题。实际接入时，如果把配置放在Nacos或Apollo里，保持同样的加载模式即可。

接着看发请求的部分。HttpClientUtil里一般会封装一个支持HTTPS的client，核心参数是连接超时、读取超时和TLS版本。下面这个示例用的是JDK自带的java.net.http.HttpClient，不引第三方依赖：

public class HttpClientUtil { private static final Duration CONNECT_TIMEOUT = Duration.ofSeconds(10); private static final Duration READ_TIMEOUT = Duration.ofSeconds(30); public static String postJson(String url, String body) throws Exception { HttpClient client = HttpClient.newBuilder() .connectTimeout(CONNECT_TIMEOUT) // 连接超时，单位秒 .sslContext(SSLContext.getDefault()) .build(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .timeout(READ_TIMEOUT) // 读取超时，单位秒 .header("Content-Type", "application/json;charset=UTF-8") .POST(HttpRequest.BodyPublishers.ofString(body)) .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); return response.body(); } }

参数说明：连接超时设在10秒比较合理，因为外网链路抖动时，10秒足够让TCP握手完成重试。读取超时30秒是照顾银行侧较重的报文处理，但不要超过60秒，否则请求堆积会把本地线程池压垮。生产环境推荐把这两个值放到配置里，方便在联调期调整。

发起缴费订单的代码在PayOrderService里。核心步骤是：构造请求参数Map，过滤空值，按ASCII排序拼接签名串，用SHA256withRSA签名，最后把参数和签名一起POST到网关：

public String createPayOrder(BridgeConfig config, String orderNo, String amount, String payerName) throws Exception { // 1. 按业务字段构造参数，key用接口文档里的字段名 Map<String, String> params = new TreeMap<>(); params.put("merchantNo", config.getMerchantNo()); params.put("orderNo", orderNo); params.put("payAmount", amount); params.put("payerName", payerName); params.put("notifyUrl", config.getNotifyUrl()); params.put("timestamp", DateTimeUtil.now()); // 2. 在这里调用签名工具，生成sign字段 String sign = SignUtil.sign(config.getMerchantPrivateKey(), params); // 3. 把sign放回参数里，序列化成JSON发送 params.put("sign", sign); String json = JsonUtil.toJson(params); return HttpClientUtil.postJson(config.getGatewayUrl() + "/order/pay", json); }

这段代码背后有一个容易被忽略的顺序问题：拼签名时要把sign字段排除在外，把其他所有字段放进TreeMap。因为TreeMap本身就按key的字典序排列，省掉了手写排序。如果后续加了自定义字段，一定要保持字段名和签名时的key完全一致，多一个空格都会导致生产环境验签失败。

3.3 异步通知的接收与应答

下单接口返回后，真正的结果是通过异步通知送过来的。DEMO里的NotifyReceiver是一个Spring MVC的Controller，接收POST请求，做验签、幂等处理、业务更新，最后返回固定应答串。

@RestController public class NotifyReceiver { @PostMapping("/notify") public String receive(@RequestBody String rawBody, @RequestHeader("X-Sign") String signHeader) { // 1. 拿到平台公钥验签，验签失败直接返回FAIL if (!SignUtil.verify(platformPublicKey, rawBody, signHeader)) { return "FAIL"; } // 2. 解析报文，查本地订单，比对金额 Map<String, String> params = JsonUtil.parse(rawBody); String orderNo = params.get("orderNo"); String payAmount = params.get("payAmount"); // 3. 这里做幂等：同一笔订单重复通知时直接返回SUCCESS if (orderService.isProcessed(orderNo, params.get("notifyId"))) { return "SUCCESS"; } // 4. 更新订单状态，落库 orderService.updateOrder(orderNo, params.get("payStatus"), payAmount); // 5. 应答，银行侧收到SUCCESS后停止重发 return "SUCCESS"; } }

应答字符串是异步通知里最关键的一环。银行侧没收到约定的成功应答，会按重试策略继续推送，常见的是1分钟、5分钟、30分钟间隔递增。所以这里的逻辑很明确：业务处理成功才返回SUCCESS，处理失败或验签失败就返回FAIL，让它继续重发。

本地联调时，想让农行测试环境的异步通知打到本地，常见做法是用内网穿透工具把本机8080端口暴露成公网地址，再把bridge.notifyUrl配置成那个公网地址。这一步不复杂，但要在配置文件中把notifyUrl改成“公网地址+/notify”，否则会出现“下单成功但一直收不到通知”的现象。

4. 签名、加密与时间戳：V1.4里三个必调参数

4.1 签名串的拼接规则与SHA256withRSA实现

农行BRIDGE这类银行开放接口，签名算法基本都走RSA体系。V1.4的DEMO里用的是SHA256withRSA，这一点可以从SignUtil.java里一眼确认。真正需要花心思的不是算法本身，而是“签名字符串怎么拼”。

最常见的规则是：把所有参与签名的参数按key的ASCII字典序升序排列，每个参数写成key=value，再用&连接，最后把拼接结果交给签名算法。下面这段就是签名工具的核心：

public class SignUtil { private static final String ALGORITHM = "SHA256withRSA"; private static final String CHARSET = "UTF-8"; public static String sign(PrivateKey privateKey, Map<String, String> params) throws Exception { // 1. 拼接待签名串：只拼非空值，排除sign本身 String content = buildSignContent(params); // 2. 调用JCE签名，注意指定UTF-8 Signature signature = Signature.getInstance(ALGORITHM); signature.initSign(privateKey); signature.update(content.getBytes(CHARSET)); // 3. Base64输出签名串 return Base64.getEncoder().encodeToString(signature.sign()); } public static boolean verify(PublicKey publicKey, String content, String sign) throws Exception { Signature signature = Signature.getInstance(ALGORITHM); signature.initVerify(publicKey); signature.update(content.getBytes(CHARSET)); return signature.verify(Base64.getDecoder().decode(sign)); } private static String buildSignContent(Map<String, String> params) { // TreeMap自动按字典序排序，过滤空值和sign字段 Map<String, String> sorted = new TreeMap<>(); for (Map.Entry<String, String> entry : params.entrySet()) { String key = entry.getKey(); String value = entry.getValue(); if ("sign".equals(key) || value == null || value.isEmpty()) { continue; // 空值不参与签名 } sorted.put(key, value); } StringBuilder sb = new StringBuilder(); for (Map.Entry<String, String> entry : sorted.entrySet()) { if (sb.length() > 0) { sb.append("&"); } sb.append(entry.getKey()).append("=").append(entry.getValue()); } return sb.toString(); } }

逻辑说明：buildSignContent里有两个硬性规则必须保住。第一个是TreeMap的排序，这决定了拼接顺序，任何一处手写排序都要避免，因为字符串比较和字节排序可能不一致。第二个是“空值不参与签名”，这不只是减少麻烦，而是银行侧的验签程序就是这么实现的，你多拼一个空字段，两边原文就永远对不上。

这里很容易踩的一个细节：请求参数在发出去的时候要把sign放回参数Map里一起序列化，但拼签名原文时又要把它排除。有的人图省事把整个Map直接循环一遍，签出来的串在本地自测永远是对的，因为本地没有平台验签，等到联调时才暴露。租下来一条经验，DEMO里的SignTest这个测试类，就是专门用来验证签名工具和文档示例是否一致的，跑这个测试应当成为改代码后的第一件事。

4.2 平台公钥、商户私钥、时间戳：三个必须核对的参数

对完签名逻辑，真正决定“联调能不能一次过”的是三个参数：平台公钥、商户私钥、时间戳。这三个参数在DEMO里都有默认值，但各有各的坑。

第一个是商户私钥。银行侧签发的私钥通常是PKCS8格式，而很多程序员以前用的开源工具默认生成PKCS1格式。两种格式的PEM文件头不同，加载方式也不同。如果加载时发现“只差一行头文件”的报错，多半是私钥格式没对齐。

第二个是平台公钥。平台公钥是用来验异步通知签名的，它和商户私钥是一对一对的不假，但平台公钥的版本更新会变。很多生产事故都出在“联调用的是老版本平台公钥，上线前平台侧的密钥轮换没同步”，导致上线当天所有异步通知验签失败。

第三个是时间戳。这个参数很容易被忽略，但它承担的是防重放攻击的作用。银行侧拿到请求后会检查timestamp与网关服务器当前时间的偏差，超过窗口就拒绝。联调时如果商户服务器时间没同步，或者时区不对，会间歇性出现“上一笔能通、下一笔就报时间过期”的玄学问题。

这个表格值得打印出来贴在工位边上。我见过太多联调周被这三个参数折磨的团队，最后发现不是代码写错，是密钥文件从测试环境拷到生产环境时被Windows记事本改坏了换行符。

4.3 调试时最该开的三类日志

调试银行对接，日志的详细程度直接决定排查效率。我一般会要求项目里至少开三类日志：请求响应报文日志、HTTP调用耗时日志、验签结果日志。

报文日志要打原始请求和响应，但不要盲打。卡号和证件号这类敏感字段要先做脱敏再输出，简单的方式是统一走一个LogUtil.mask()方法。耗时日志主要记录每次POST网关的耗时，银行侧接口在联调期经常有偶发慢请求，没有耗时记录很难确认是网络抖动还是银行侧处理慢。验签结果日志要把验签时的原文和签名串也打出来，方便和银行侧核对。

logging: level: com.abchina.bridge.demo.core: DEBUG com.abchina.bridge.demo.service: INFO org.apache.http.wire: ERROR

这个配置的意思是：核心工具包打DEBUG，方便看签名原文；业务服务打INFO，避免日志刷屏；HTTP client的wire日志必须关掉或打到ERROR，因为wire日志会打印超文本传输协议的原始字节流，里面可能带着完整报文，既大又敏感。生产环境连DEBUG都不要开，只在联调阶段短暂开启。

5. BRIDGE商户直连接入避坑盘点

5.1 本地跑通、上线验签失败：私钥格式与换行符

现象：本地联调一切正常，代码原封不动部署到生产，第一次请求就返回验签失败。

原因：八成是私钥文件在传输或部署过程中被改动过。最常见的是从Windows传输到Linux服务器后，PEM文件末尾的换行符从\r\n变成了\n，或者文件被文本编辑器打开保存过一次，行尾被重写。这类问题用编辑器看文件时一点异常都看不出来，但程序加载出来之后密钥字节就变了。

解决：部署后第一时间用命令行做一次密钥指纹校验，对比本地和服务器上的私钥SHA256值，如果不同就重新上传，并且上传用二进制模式。我的习惯是把密钥文件放进配置管理系统时固定用base64转储，应用启动时解码加载，能彻底避开换行符问题。

5.2 异步通知收不到：回调地址和应答体不对

现象：下单接口调用成功，日志里能看到响应报文，但商户系统一直收不到异步通知。检查回调地址配置，看起来也没问题。

原因：两种情况最常见。一种是回调地址配在了内网地址或公网不可达的域名上，银行侧的服务器根本访问不到。另一种是回调接口返回的应答体不对，银行侧只认文档里约定的成功应答串，返回了普通JSON或HTTP 200但内容是{"code":0}，会被当成失败继续重发。

解决：联调阶段先用curl从外网访问一下notifyUrl，确认能通。再检查Controller返回值，必须原样返回文档约定的字符串，注意大小写和空格。这类问题的排查思路很简单，但每次接入都会有人踩，因为它藏在“明明下单成功了”的错觉背后。

5.3 中文乱码：UTF-8与GBK的混用

现象：缴费项目名称、缴费人姓名在收到异步通知后显示乱码，或者下单请求里传中文导致签名失败。

原因：本地开发环境默认UTF-8，但生产服务器的操作系统可能使用了GBK或其他默认字符集。DEMO里明确配置了bridge.charset=UTF-8，但Controller接收请求时，如果Spring Boot没有显式设置字符集，容器的默认编码可能跟随系统。

解决：在application.properties里补上server.servlet.encoding.charset=UTF-8和server.servlet.encoding.enabled=true。更保险的做法是在HttpClientUtil里显式指定UTF-8，同时确保代码里所有字符串转字节的操作都带Charset参数，不要用getBytes()无参版本。乱码在联调阶段不一定会暴露，因为有些开发环境碰巧都是UTF-8，生产环境一换就现原形。

5.4 重复通知导致重复下单：幂等表必须建

现象：本地单测时手动重发了两次通知，发现数据库里生成了两笔相同的订单。

原因：银行侧的重试机制会带来重复通知，网络抖动也可能让同一通知被发送多次。异步通知接口如果只判断“订单存在就不处理”，那么正在处理中或已完成的订单仍可能被重复更新。

解决：建一张通知幂等表，唯一键用“商户号+订单号+通知编号”，处理前先插入记录，插入冲突就直接返回SUCCESS。注意不要把唯一键只建成“订单号”，因为同一订单的重试通知需要被识别为重复，但真正的不同通知编号要能被记录。这个表还能顺便记录通知到达时间，排查问题时有据可查。

5.5 对账文件里的金额和时区

现象：日终对账时发现银行侧文件和本地订单的金额对不上，有的差几分钱，有的差一整天。

原因：金额单位不一致。接口报文里的金额可能以分为单位传整数，对账文件里的金额却可能带小数，或反过来。另一个坑是文件里给的交易日期可能用UTC+8以外的时间格式，解析成Java的LocalDateTime时没有指定时区，导致跨天订单被算到前一天。

解决：对接第一件事就把文档里的金额单位拿出来核对，明确“元”还是“分”，写一个转换工具类统一口径。时间字段解析时用带时区的OffsetDateTime，或者显式指定ZoneId.of("Asia/Shanghai")。这类问题排查起来非常耗时，因为它不会报错，只会让数字悄悄不对。

6. 从DEMO到生产：上线前这样验证

有机会把DEMO真正推到生产的人，一定会在上线前那一周重新审视整个对接质量。我的做法是列一个十项左右的验证清单，一项一项过，不凭感觉。

上线前替换配置的四项要单独拎出来核对：商户私钥、平台公钥、网关地址、回调域名。这四项里任何一项用了测试环境的值，生产都会在第一批请求时报错。我习惯在启动时打印一份“配置指纹”，就是商户号、密钥文件SHA256、网关地址的缩写，登录生产服务器看一眼就知道环境对不对。

对账文件的定时拉取是另一个容易后补的功能。不要把它放在异步通知里顺带做，通知只是单笔结果，对账文件才是日终闭环。常见做法是单独跑一个定时任务，凌晨拉取前一天文件做逐笔核对，差异结果写到告警表。定时任务框架可以用Spring自带的任务，也可以用成熟的调度框架，但核心是把“对账”和“通知”这两条责任链分开，谁出了问题都能独立定位。

最后说个我自己的教训。有一年上线前，我检查了代码、换了密钥、配了新网关，唯独没有确认平台公钥的版本。联调阶段一直是老版本，上线当天银行侧把平台公钥切到了新版本，结果所有异步通知验签失败，整个缴费入口瘫痪了一个上午。从那以后，每次环境切换，我第一件事就是打印公钥的指纹，对比看过才继续。这套BRIDGE DEMO本身写得很完整，但DEMO帮你省掉的只是“拼报文”的重复劳动，密钥、环境、时间戳这些活，还是得自己一步步验证到位。希望帮到你。

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