简介一套基于Java的易宝支付对接源码适合需要快速接入第三方支付或学习支付网关接口的Java Web开发者。资源已实测成功附带完整测试步骤截图清晰展示从登录选择银行、提交订单到建行网银扣款0.01元并收到回调通知的完整过程。压缩包共36个文件以Java源码、JSP页面、class文件、properties及xml配置为主另含jar依赖、测试结果图片和说明文档整体约786KB目录紧凑便于本地部署与调试。目前已有1491人学习下载代码中保留了商户ID、回调地址等关键配置位置可直接参考其参数组装、hmac签名校验及支付结果处理逻辑对理解易宝支付网关交互机制很有帮助。1. 一套 Java 易宝支付源码先看它解决了什么再看值不值得下载做支付对接的人都有种体会接口文档读三遍不如一份能跑的代码。这套易宝支付 Java 源码卖点在标题里就说透了——已测试成功附测试步骤图片。它不是那种“代码齐全但一跑就崩”的陈列品而是把网关支付请求、MD5 签名、异步回调验签、订单更新这一条完整链路走通了的模板。适合马上要在 Java 项目里接入易宝支付又不想从零研究签名规则的开发者也适合接手老项目、需要一份对照实现来排查问题的同学。下文按“原理、配置、踩坑、测试”的顺序拆开讲每个环节都能直接对到源码里的文件。2. 易宝支付网关链路和源码结构先分清五个参与方支付对接最容易犯的错是把流程想象成“客户端请求后端后端请求网关网关同步返回结果”。真实情况是网关支付和登录验码不一样支付成功后易宝的支付结果不是跟着用户浏览器回来的而是由易宝后台单独发起一条异步通知打到你在支付请求里配置的回调地址上。所以一套完整的易宝对接源码至少要有两个入口一个是发起支付的请求入口一个是接收支付结果的通知入口。两个入口共用同一套签名和验签逻辑这就决定了“签名工具类”在整个项目里的核心地位。这条链路里真正干活的参与方有五个用户浏览器、发起支付的后端服务、易宝支付网关、易宝后台通知服务、承载订单状态的数据库。用户付完款之后浏览器跳回你的同步返回地址那是给用户看的页面不代表订单就成功了真正可信的是易宝后台向你的异步通知地址发的那条 POST 请求。这套源码能跑通本质上就是把同步跳转和异步通知这两个入口分别处理对了。2.1 一次支付里代码要处理的四个关键节点一次完整交易在源码里会经过四个节点按顺序看用户点“去支付”后端查出订单按易宝文档给定的顺序组装参数后端生成签名后输出一个自动提交的 HTML 表单由浏览器跳到易宝网关用户支付完成后浏览器同步跳回同时易宝后台向 p8_Url 发异步通知后端收到异步通知验签、核对金额、更新订单并返回固定的 SUCCESS 字符串。四个节点里最容易误解的是第三和第四之间的边界。同步跳转告诉用户“你付完了”但它不带可靠的交易回执也不保证一定到达所以不能作为更新订单的依据异步通知才是支付平台和后端服务器之间的正式握手。源码里 PayStartServlet 承担节点二PayCallbackServlet 承担节点四两端共用同一个 SignUtil这是源码里最值得先读的三文件组合。二次开发时常见的问题是有人把签名工具里的参数顺序动了一下发起支付没问题回调验签却立刻失败。原因很简单回调方用的是下单时那套参数规则你对任何一端改了顺序、漏了字段两边的签名串就对不上所有验证全部失败。2.2 接口参数表先认识易宝网关交易的每个字段支付请求的主体参数在源码里被封装在 PayRequest 类中。下面这张表是这套源码实际拼参数时用到的核心字段也是测试排错时的对照基准参数含义必填/样例p0_Cmd业务类型Buyp1_MerId商户编号测试商户号数字串p2_Order订单号长度不超过 20 位保证唯一p3_Amt支付金额字符串格式两位小数如 199.00p4_Cur币种CNYp5_Pid商品名称展示在收银台p6_Pcat商品分类可选p7_Pdesc商品描述可选p8_Url异步通知地址必须公网可达不能填 localhostp9_Saf_Flg跳转策略1 跳转易宝收银台0 使用 pd_FrpIdpa_MP商户扩展字段最长 200 字回调时原样返回pd_FrpId支付通道编码填银行编码则直达留空则进收银台自选pr_NeedResponse响应机制1表示必须异步通知hmac签名串MD5 计算32 位小写三个容易看走眼的点说在前面。第一p3_Amt 要从 BigDecimal 转成两位小数字符串直接用 double 拼“10.0”进来签名串和支付金额就都偏了。第二p8_Url 在测试环境必须配到你的公网测试机否则易宝后台通知打不进内网订单就永远停在未支付。第三pd_FrpId 留空反而更适合验证流程用户进收银台可以选不同支付方式测试覆盖面大一些。源码包里对应的文件是 PayRequest.java 和 PayResponse.java。PayRequest 把接口参数投影成下单请求PayResponse 把回调参数投影成验签结果。两个类都保留了易宝原始字段名不做过度的驼峰转换目的就是方便拿源码参数和易宝文档对照定位。很多同学习惯把 p1_MerId 改成 merchantId改完之后文档、测试步骤、日志全对不上这是二次开发里最不划算的重构。2.3 签名算法原理为什么所有参数值要按顺序进签名串这套易宝接口用的是 MD5 签名但签名规则不是把所有参数拼成 JSON而是按接口文档里参数排列的顺序把所有非空参数值拼接成一个长字符串最后再在尾部拼接商户密钥对整个字符串做 MD5 加密。服务端对原始串做同样的拼接比较结果。这意味着有两件事实打不动。第一参数顺序不能乱。顺序变了拼出来的原串就变MD5 结果就变验签就失败。这也是为什么源码里故意用 LinkedHashMap 而不是 HashMapHashMap 不保证迭代顺序里面的值多一个或少一个都会导致签名串不稳定。第二空值可以不拼。拼接规则是“参数有值才进串没有值跳过”所以 p6_Pcat、p7_Pdesc、pd_FrpId 这几个可选字段没赋值就跳过不影响签名结果。举个例子假设商户号是 1000000000订单号是 T20250101001金额是 10.00那么签名原串的大致形态是Buy1000000000T2025010100110.00CNY测试商品...商户密钥注意这个字符串中间没有等号、没有 符号和微信支付、支付宝的签名规则明显不同。调试时不要把习惯带过来否则拼出来的 raw 串永远和易宝对不上。这两个点搞清楚后后面调试验签失败基本三分钟就能定位很多人验签失败后反复去查密钥其实密钥没错是拼接规则错了。3. 把源码跑起来配置商户号、密钥和回调地址三件事拿到源码包后第一步不要急着看支付页面长什么样而是先改配置。这套源码把商户相关参数都收在了 resources 下的 pay.properties 一个文件里从项目结构上看是清爽的也方便做测试环境和生产环境切换。源码包里依赖的 jar 放在 lib 目录web.xml 放在 WebContent/WEB-INF 下src 下按 controller、service、util、entity 分了包。整套是传统 Servlet 结构打进 war 包丢进 Tomcat 就能跑没有引入重量级框架对老项目很友好。源码包内部结构大概是src/controller 放两个支付入口 Servletsrc/service 放订单查询与更新服务src/util 放 SignUtil 和 Md5Utilresources 放 pay.propertiesWebContent 放 JSP 页面和测试入口。测试步骤图片集中在文档目录里每个页面和配置项的对应关系在图上标得很清楚。这种结构的好处是搬进自己项目时不用拆框架直接把 controller 和 util 拷过去改包名即可。3.1 先改配置商户号、商户密钥、回调地址三件套pay.properties 里需要改的核心是三组配置# 商户编号测试环境用易宝商户后台里的测试商户号 merchant.id1000000000 # 商户密钥测试环境的密钥和生产环境的密钥是两套 merchant.key2f6b8c4e9a1d7f3c50e2b8a94d16c7f3 # 异步通知地址公网能访问到的完整路径 callback.urlhttp://your-server-ip:8080/pay-demo/pay/callback # 同步跳转地址用户支付完成后浏览器跳回来 return.urlhttp://your-server-ip:8080/pay-demo/pay/result这段配置里的 callback.url 是整条链路里最容易犯错的点。注意两端要一致一端是发起支付时 p8_Url 要传 callback.url 的值另一端是你在易宝商户后台签约时填的支付通知地址两者要指向同一个地址。很多项目测试不通过是因为下单的 p8_Url 填了 A 地址商户后台却配置了 B 地址易宝看到下单信息里的地址和后台登记的不一致通知直接打给后台配置的地址两边对不上订单就停在半路。测试环境里第一次跑通也不要急着把密钥换成生产的。先确认商户号、密钥、回调地址三个值的来源都是同一个环境。测试环境和生产环境的密钥是两套混用之后发起支付可能看着正常回调验签却过不了这种问题最消耗时间。3.2 发起支付参数封装、签名和自动跳转表单在源码的 PayStartServlet 里发起支付的核心逻辑是查订单、组参数、算 hmac、输出一段自动提交表单。下面这段代码是源码里的核心逻辑去掉了一些业务判断保留主链路WebServlet(/pay/start) public class PayStartServlet extends HttpServlet { Override protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { String orderId req.getParameter(orderId); Order order orderService.getByOrderId(orderId); if (order null) { resp.sendRedirect(/pay-demo/error.jsp); return; } if (!UNPAID.equals(order.getStatus())) { resp.sendRedirect(/pay-demo/result.jsp?orderId orderId); return; } LinkedHashMapString, String params new LinkedHashMap(); params.put(p0_Cmd, Buy); params.put(p1_MerId, payConfig.getMerchantId()); params.put(p2_Order, order.getOrderId()); params.put(p3_Amt, order.getAmount().setScale(2).toString()); params.put(p4_Cur, CNY); params.put(p5_Pid, order.getProductName()); params.put(p6_Pcat, ); params.put(p7_Pdesc, ); params.put(p8_Url, payConfig.getCallbackUrl()); params.put(p9_Saf_Flg, 1); params.put(pa_MP, ); params.put(pd_FrpId, ); params.put(pr_NeedResponse, 1); String hmac SignUtil.createSign(params, payConfig.getMerchantKey()); params.put(hmac, hmac); StringBuilder form new StringBuilder(); form.append(htmlbody onload\document.forms[payForm].submit()\); form.append(form namepayForm methodPOST actionhttps://www.yeepay.com/app-merchant-proxy/node); for (Map.EntryString, String item : params.entrySet()) { form.append(input typehidden name) .append(item.getKey()) .append( value) .append(item.getValue()) .append(/); } form.append(/form/body/html); resp.setContentType(text/html;charsetUTF-8); resp.getWriter().write(form.toString()); } }代码逻辑分成三段。第一段查订单并判断状态防止同一笔订单重复发起支付。第二段按易宝文档给定的参数顺序组 p0_Cmd 到 pr_NeedResponse这里最忌讳的就是有人为了少写几行把参数放进 HashMap签名全乱。第三段把参数连同 hmac 拼成自动提交的隐藏表单由浏览器代为完成跨域 POST 跳转。p3_Amt 这里用的是 order.getAmount().setScale(2).toString()没有直接 toString。BigDecimal 不显式设置保留位数可能输出 1990 或 1990.0签名字符串和网关解析金额都会出问题。setScale(2) 之后输出的一定是两位小数也只有这种写法能保证签名稳定。签名方法 createSign 的内部实现是核心中的核心单独拆开看public static String createSign(MapString, String params, String merchantKey) { StringBuilder raw new StringBuilder(); for (Map.EntryString, String item : params.entrySet()) { String value item.getValue(); if (item.getKey().equals(hmac) || value null || value.length() 0) { continue; } raw.append(value); } raw.append(merchantKey); return Md5Util.md5(raw.toString()).toLowerCase(); }这段做的事就是 2.3 说的签名规则按参数顺序把非空 value 拼在一起尾部附加商户密钥再做 MD5。这里要求传入的 params 必须是有序的 LinkedHashMap否则遍历顺序不固定签名就不可复现。这套源码里 createSign 同时服务支付请求和回调验签任何一边改动都要考虑对另一边的影响不然下单成功、回调查验失败这种奇怪现象就会找上门。3.3 回调验签用同一套签名逻辑保护订单状态回调接口 PayCallbackServlet 是这套源码的另一个入口服务端异步通知和浏览器同步跳转都会到达这里。源码里把两种请求合并处理但更新订单的逻辑只在异步通知分支执行同步跳转只做结果展示。核心代码WebServlet(/pay/callback) public class PayCallbackServlet extends HttpServlet { Override protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { LinkedHashMapString, String params new LinkedHashMap(); params.put(r0_Cmd, req.getParameter(r0_Cmd)); params.put(r1_Code, req.getParameter(r1_Code)); params.put(r2_TrxId, req.getParameter(r2_TrxId)); params.put(r3_Amt, req.getParameter(r3_Amt)); params.put(r4_Cur, req.getParameter(r4_Cur)); params.put(r5_Pid, req.getParameter(r5_Pid)); params.put(r6_Order, req.getParameter(r6_Order)); params.put(r7_Uid, req.getParameter(r7_Uid)); params.put(r8_MerId, req.getParameter(r8_MerId)); params.put(r9_BType, req.getParameter(r9_BType)); params.put(rp_PayDate, req.getParameter(rp_PayDate)); String hmac req.getParameter(hmac); if (!SignUtil.verifySign(params, payConfig.getMerchantKey(), hmac)) { resp.getWriter().write(FAIL); return; } if (!1.equals(req.getParameter(r1_Code))) { resp.getWriter().write(FAIL); return; } // 只有异步通知才更新订单BType2 代表异步通知 if (2.equals(req.getParameter(r9_BType))) { String orderId req.getParameter(r6_Order); String trxId req.getParameter(r2_TrxId); String payAmount req.getParameter(r3_Amt); boolean updated orderService.markPaidIfMatch(orderId, payAmount, trxId); if (!updated) { resp.getWriter().write(FAIL); return; } } resp.getWriter().write(SUCCESS); } Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { // 同步跳转只展示页面订单状态由前端调查询接口刷新 resp.sendRedirect(/pay-demo/result.jsp?orderId req.getParameter(r6_Order)); } }验签通过后r1_Code 等于 1 表示支付成功r9_BType 等于 2 才被认为是异步通知可以更新订单。同步跳转的请求一律不碰订单表只刷新结果页面让用户看到“支付确认中”的中间状态。这里有个细节markPaidIfMatch 方法内部会比较回调金额和数据库订单金额是否一致这是防止金额被篡改的关键防线不能省。回调接口返回 SUCCESS 之前不能再写其他内容到响应里也不能先调用 sendRedirect否则 Servlet 容器会抛 IllegalStateException易宝侧收到非预期的响应会认为处理失败。生产上建议在回调入口加一行业务日志收到回调订单号是 r6_Order来源是 BType 的值。这一行日志在后续排查重复通知、丢失通知时非常有用。4. 避坑易宝支付对接里最容易翻车的五个细节支付对接的坑不像普通业务代码报错信息往往就一行“验签失败”或“数据不对”排查起来很玄学。下面五条是从源码测试记录里整理出来的高频问题全部按现象、原因、解决的方式记录照着查能省大半天。4.1 回调验签失败日志里只有一句签名不对现象测试支付时用户在收银台付了钱浏览器也跳回成功页了但服务端日志里签名校验不通过订单没更新。原因最常见的是两处。一是发起支付用的是 LinkedHashMap回调验签却用了 HashMap遍历取值顺序不一样签名串就变了二是回调接口漏取了某个参数比如 rp_PayDate 没放进验签集合导致拼接串和易宝计算时少了内容。解决把回调验签参数也改成 LinkedHashMap并且严格对照易宝回调文档里的参数顺序来 put。改完后再测一次九成验签失败是这样解决的。若还失败把验签用的原始拼接串打出来和易宝签名串逐位对比差在哪个字符就改哪个字段。4.2 用户付了钱订单还是未支付现象收银台已完成支付异步通知也收到了但数据库里订单状态还是 UNPAID。原因订单更新逻辑只应在异步通知分支执行但更新前的状态校验没写或者用了“先更新后判断”的写法另一个常见原因是回调返回的字符串大小写不对易宝要求返回大写 SUCCESS如果返回了 success 或空易宝会判定处理失败持续重发通知。解决更新订单前先查一次订单状态存在且为 UNPAID 再更新接口返回固定字符串 SUCCESS。注意易宝识别的是原样输出的 SUCCESS 四个英文大写字母任何 JSON 包装、空格、大小写差异都会被当成处理失败。响应内容长度保持最短不要带业务状态码避免网关解析异常。4.3 金额对不上回调里的 amt 和订单差一分钱现象下单金额是 9.90回调金额却是 9.9数据库一比较就失败。原因金额在发起支付时没做 setScale(2)下单的时候把 9.9 拼给了 p3_Amt网关在回调时原样返回 9.9而数据库字段或 Java 比较时又按 9.90 的格式校验两个字符串不等。解决统一规定金额的字符串格式。下单和回调比较都用 BigDecimal 的 setScale(2, RoundingMode.HALF_UP)不要用字符串 equals 直接比。数据库金额字段建议用 decimal(10,2)从源头保证格式一致。4.4 本地联调异步通知始终收不到现象本地起了服务也能发起支付但支付完成后回调接口没任何日志订单也不更新。原因易宝后台通知只能访问公网localhost 或内网地址是不行的。本地联调没有公网入口通知自然打不进来这是最容易被忽视的环境问题。解决测试阶段把回调地址配到一台有公网 IP 的测试服务器上或者用公司已有的测试环境域名转发到开发机。等本地逻辑验证完再把回调地址切回真实测试环境。不建议把生产回调地址拿来测试免得污染生产订单数据。4.5 异步通知重复到达订单状态被覆盖现象支付完成后订单被正确置为已支付但过了几分钟日志里又出现同一条回调订单状态反而变成了已取消或者异常。原因易宝为了可靠性会重发异步通知直到收到 SUCCESS。如果更新订单时不检查当前状态直接无条件更新重发的通知可能把已支付状态覆盖成其他值。解决订单状态更新要做幂等处理。状态只有 UNPAID 才能流转到 PAID如果已经是 PAID相同的回调直接返回 SUCCESS不做任何变更。源码里的 markPaidIfMatch 在 SQL 里带上了 stateUNPAID 条件配合 UPDATE 影响行数为 0 时直接返回这是最稳的做法。5. 按源码包的测试步骤跑一遍从测试环境到回调落地源码包里附带测试步骤图片这一步把截图背后的操作补全。测试环境与生产环境的关键区别在于商户号和密钥不同支付后的资金流是虚拟的但代码路径和生产几乎一致所以这套步骤跑通后切生产只需要改配置和重新部署不用动业务代码。5.1 测试前必改的三项配置第一项是 pay.properties 的商户号与密钥。第二项是项目部署的上下文路径确保 pay/start 和 pay/callback 两个地址与你实际部署路径一致。第三项是异步通知地址测试环境建议填测试服务器的公网地址或公司测试环境域名并确保端口在安全组里放开。配置完成后用两个 curl 命令做快速连通检查一个看项目是否正常启动一个看回调地址是否能被外部访问# 检查项目是否启动成功 curl -I http://your-server-ip:8080/pay-demo/pay/start # 检查回调地址是否能被外部访问POST 一个空请求 curl -X POST http://your-server-ip:8080/pay-demo/pay/callback第一个命令期望返回 302 或 200不报 404 或 500。第二个命令即使验签失败也要能收到 FAIL 而不是连接超时连接超时说明回调地址不可达需要先解决网络问题再继续往下测。5.2 完整跑通一笔 0.01 元订单的测试步骤按源码包里的测试步骤图片测试订单金额统一用 0.01金额越小越不容易出错。测试流程分成下面几步在测试页面录入一个测试商品生成订单号并保存到数据库订单状态初始为 UNPAID。浏览器访问支付发起接口携带订单号参数触发自动提交表单跳转到易宝网关。在网关收银台选择测试支付通道按易宝开放平台提供的测试支付指引完成支付。支付完成后观察两个结果浏览器是否同步跳回 return.url服务端日志是否出现回调请求其中一条 r9_BType 为 2。查数据库订单状态是否变为 PAID同时确认数据库里记录了易宝的交易流水号 r2_TrxId。这个顺序应该和源码包的测试步骤图片一一对应。如果哪一步断了优先看服务端日志。日志里最容易认的是“回调验签通过订单更新成功”之类的业务日志没有这行日志就说明卡在验签或网络链路。测试通过后可以把支付通道切到真实的小额银行卡通道再验证一次用真实资金走通一遍全链路生产上更放心。5.3 验证回调链路的三个必要检查点回调链路不能只看订单状态三个检查点能确认整条链路是健康的。第一个检查点回调日志里出现两条不同 BType 的记录一条是 1一条是 2。只有 BType 为 2 的异步通知触发订单更新若只有 1说明你把更新订单逻辑写在了同步跳转里这在生产环境是不可靠的。第二个检查点数据库支付流水表里的 trx_id 与易宝侧的交易号保持一致且金额字段是两位小数格式。第三个检查点回调接口返回给易宝的响应内容是纯粹的 SUCCESS。如果易宝重发了超过三次通知说明响应体被改成了 JSON 带引号或带了业务状态码被网关判定为失败。6. 进阶一点把易宝回调结果统一成自己的 PayResult让业务层不碰易宝字段测试通过只代表能跑通工程上还有一件事值得做把易宝的字段包在自己的结果对象里业务层不要直接依赖 r6_Order、r1_Code 这些易宝命名。否则将来换支付渠道或新增一个渠道网关时业务方法全都要改。处理思路很直接。定义一个 PayResult 只留业务关心的字段渠道字段在回调入口处转换public class PayResult { private String orderId; private String channelTradeNo; private boolean paySuccess; private String rawCallback; }在 PayCallbackServlet 里验签并且 r1_Code 等于 1 之后把易宝参数塞进 PayResult再交给 orderService 处理。这样订单服务只认识 orderId 和 paySuccess支付渠道变成可替换的适配器。将来接入别的支付平台只需要在新渠道的入口里做同样的转换。验证这种改动是否安全可以做一个简单的回归拿第 5 章测试时留下的回调参数写一个 Mock 请求在本地回放不断比较重构前后的订单更新结果是否一致。回放时重点关注回调参数里缺失字段和多余字段的处理确保 PayResult 的 rawCallback 完整保留了原始内容排障时还能拿到第一手信息。从那以后我每接到一个支付对接任务都会强制自己做一遍先画一次链路图确认异步通知入口再写渠道适配接口最后才动业务代码。支付对接的大坑从来不在代码量的多少而在签名顺序、回调幂等和金额格式这些细节上。希望这套源码的拆解能帮到你拿过去改改配置跑通一遍测试链路比一个人面对文档摸索心里有数得多。本文还有配套的精品资源点击获取