简介XPay V3.1是一套基于Java开发的个人收款支付系统专为个人站长、独立开发者及小微企业设计完全免费且无需签约生成个人收款码后即可收款交易资金直接进入本人账户有效破解传统支付接入门槛高、结算周期长的痛点。压缩包共含416个文件、约16.39MB代码层覆盖24个Java核心模块、31个HTML页面、54个JavaScript脚本、26个CSS样式及210张PNG图片可支撑完整的前端交互和管理后台另附PDF使用必读、DOCX说明文档、API接口与配置文件等部署、学习和二次开发所需资料一应俱全。系统内置收款码生成、交易订单管理、退款处理、SSL加密传输及API接口既能独立运行也可嵌入已有网站或App方便快速搭建免签约个人收款能力。源码与文档目录结构清晰关键路径和配置项都有对应说明初中级开发者可依据资料完成环境搭建、参数调整和功能扩展。目前已有696人浏览/学习适合需要低成本接入个人收款或研究Java支付实现的开发者参考。1. XPay 是干什么的不签约、资金直达到账的 Java 收款方案上个月一个做独立站的哥们找我说他的工具站要收会员费但手里没有公司主体申请不到微信支付商户号问我有没有别的路子。我直接给他搭了一套 XPay V3.1用户扫他的个人收款码钱实时进他自己微信或支付宝XPay 在后台监听这笔到账再自动回调业务系统把订单标记成已支付。整个过程不涉及签约资金也不经过 XPay本质是把「线下到账」和「线上订单」连接起来的中间层对个人开发者来说是最省事的 Java 收款落地方式。下面从原理到部署把 XPay V3.1 的源码和完整链路拆开过一遍它靠什么机制感知到账、数据库怎么设计、部署时哪些参数不能乱填、二次开发时回调验签和订单状态机怎么写才不容易出事故。适合被商户号资质卡住、想在自建站或工具箱里接入个人收款的 Java 工程师也适合后端团队里负责支付回调模块的开发者。2. 从扫码到回调XPay 的核心链路与模块拆解2.1 核心原理没有官方网关它靠什么确认「钱到了」先对齐一个认知XPay 不是支付网关不碰资金清算。用户的每一笔付款都是直接打到收款人本人的微信或支付宝账号XPay 只负责替业务系统确认到账这步动作。官方支付网关会主动告诉你「订单已支付」但个人收款场景没有官方回调通道XPay 得自己想办法感知到账事实。它怎么感知常见做法是两条路线并行。一条是 notify 路线monitor 监听端挂在装有收款账号的设备或通知通道上实时捕获微信或支付宝的到账通知解析出金额、付款方备注和时间响应最快用户体验最好。另一条是 poll 路线XPay 定时去查询账单或钱包流水专门兜底 notify 失效的场景。V3.1 源码的 monitor 模块把两种策略都做了封装配置里用 strategy 参数切换生产环境我一般开 notify 为主、poll 兜底。到账事件解析出来之后XPay 不会立刻回调业务系统中间还有一道订单匹配把这次到账的金额和备注拿去和订单池里的待支付订单比对匹配成功才更新订单状态、触发回调。这里就产生了一个天然约束——匹配准确度决定了整个系统的可靠性。两笔订单金额相同、又都没有备注系统只能靠猜猜错就是串单事故。V3.1 里匹配逻辑走的是金额加备注双因子先按金额过滤再用备注里的短单号做精确匹配。这要求下单环节必须把备注生成好并展示给用户用户付款时没填备注到账就落到「待人工确认」由后台人工核对后手动完成回调。2.2 源码包结构server、monitor、admin、callback 各管一段从部署视角看XPay V3.1 编译后是两条可执行单元xpay-server 和 xpay-monitor。前者是主服务后者是到账监听进程两个都是 Spring Boot 应用共用同一个数据库。源码内部按职责拆成四个模块我第一次拆包时是按这个分组去读的模块运行形态核心职责xpay-serverSpring Boot 单体应用下单 API、订单查询、管理后台页面、回调投递xpay-monitor独立 Java 进程到账通知监听、消息解析、订单匹配adminserver 内置 Web 页面订单列表、人工确认、补单、回调记录查看callbackserver 内部组件回调任务队列、失败重试、回调结果落库server 里的 controller 包跟接口基本一一对应OrderController 负责/api/order/create和/api/order/queryAdminController 负责后台管理接口CallbackController 负责补单和回调记录查询。service 层里最值得看的是 OrderService 和 CallbackService前者封装了下单、状态流转、超时关闭后者封装了回调投递和重试策略。monitor 是一套独立逻辑不对外提供 HTTP 服务启动后就是一个常驻进程。它解析到到账事件后调用与 server 共用的订单匹配模块更新订单状态同时把一个「待投递」标记写入回调队列。注意这里 monitor 只负责更新状态和投递标记实际发送 HTTP 回调的是 server 里的 callback 组件。这样即使 monitor 和 server 分开部署回调仍然统一从 server 发出避免两条链路同时外发产生重复通知。2.3 订单表结构与状态流转五个状态别搞混订单表是整个系统最重要的一张表核心字段如下字段类型说明order_novarchar(32)内部订单号创建时生成全局唯一merchant_idvarchar(32)商户标识对应业务系统的项目代号amountdecimal(10,2)订单金额单位元精确到分statustinyint0 待支付 / 1 已支付 / 2 已回调 / 3 人工确认 / 4 已关闭notify_urlvarchar(256)业务系统回调地址下单时传入notify_countint已回调次数每次重试加一notify_msgvarchar(1024)最近一次回调返回内容排查问题首选字段pay_timedatetime到账检测时间null 表示未支付create_timedatetime下单时间状态流转主线是 0 到 1 到 2下单是 0monitor 匹配到到账后置为 1callback 成功收到业务系统返回的 200 后置为 2。3 是兜底状态到账金额对不上、备注缺失、自动匹配失败时订单落到这里等人工处理人工在后台确认后可以把它置为 1再走一遍正常回调流程。4 是关闭态订单超时未支付、或回调重试次数耗尽后手动关闭关闭后不再进入任何自动流程。notify_msg字段是我排查问题时第一个看的地方。回调相关的问题九成能在这个字段里找到答案业务系统返回了什么状态码、具体什么错误信息、有没有超时。数据库初始化脚本在源码包 sql 目录下MySQL 用 init_mysql.sqlSQLite 用 init_sqlite.sql字段一致只是语法略有差异。提示生产环境不建议用 SQLite 跑并发写入和锁处理都不如 MySQL 稳本地验证时图省事可以用。3. 本地部署与跑通从 JDK 到第一笔真实到账3.1 环境准备JDK 版本、Maven 仓库与数据库初始化XPay V3.1 是 Spring Boot 2.x 的 Java 项目环境要求不算高JDK 8 和 11 都能跑Maven 3.6 以上就能打包数据库支持 MySQL 5.7 以上和 SQLite 3.x。唯一要提前决定的点是数据库选型生产环境直接 MySQL本地验证用 SQLite 最顺手订单量不大完全没有性能问题。组件版本建议备注JDK1.8 或 11版本再高没试过建议按源码 pom 里依赖为准Maven3.6mvn clean package打可执行 fat jarMySQL5.7生产首选字符集必须 utf8mb4SQLite3.x本地验证可用不推荐生产长时间跑Redis不需要单机版回调队列在进程内存里不依赖 Redis如果是 MySQL先建库建账号再执行源码包里的初始化脚本CREATE DATABASE xpay DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; GRANT ALL PRIVILEGES ON xpay.* TO xpay_user% IDENTIFIED BY xpay_pass_2025; FLUSH PRIVILEGES;建完库之后把sql/init_mysql.sql里的建表语句执行一遍。这里有一个经常被忽略的细节JDBC URL 里必须带useUnicodetruecharacterEncodingutf8不然中文备注落库会乱码。备注恰恰是订单匹配的关键信息乱码等于直接丢单后面全是脏数据。3.2 配置文件application.yml 里不能乱填的四个参数源码包配置集中在src/main/resources/application.yml我改完一份用于生产的配置长这样server: port: 8080 spring: datasource: url: jdbc:mysql://127.0.0.1:3306/xpay?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: xpay_user password: xpay_pass_2025 xpay: merchant-id: M2024001 secret: 96a6f13d4a0f4d6fbca0b3c4f5e6d7e8 callback: retry-times: 5 retry-interval: 3000 monitor: strategy: notify四个参数逐个说。merchant-id是当前部署实例的商户标识业务系统下单时要传同一个值XPay 用它区分请求来源填错会导致下单直接被拒。secret是回调签名密钥XPay 回调你的业务系统时会用这个 secret 对参数做 HMAC-SHA256 签名你的业务系统里必须存一份一模一样的两边不一致回调全部验签失败。这是整个系统的安全底线不要用默认值我生产环境都是 32 位随机字符串。retry-times和retry-interval控制回调重试通知发送失败后XPay 按固定间隔重试次数用完后订单停在此刻转人工处理。个人项目我会把 retry-times 调到 5宁可多重试几次也不要漏通知漏掉一笔不是一个订单的问题是用户已经付款但业务系统不发货的客诉。monitor.strategy选 notify 还是 poll取决于部署监控端的条件。notify 实时性好但要保持监听通道在线poll 适合没有持久通知通道的环境代价是有延迟我一般两个同时开。3.3 打包启动先起 server再起 monitor配置改完打包启动两件事# 打包跳过测试 mvn clean package -DskipTests # 启动主服务 java -jar target/xpay-server-v3.1.jar \ --spring.datasource.urljdbc:mysql://127.0.0.1:3306/xpay?useUnicodetruecharacterEncodingutf8useSSLfalse \ --spring.datasource.usernamexpay_user \ --spring.datasource.passwordxpay_pass_2025 # 启动监听端端口和 server 分开 java -jar target/xpay-monitor-v3.1.jar \ --server.port8081 \ --spring.datasource.urljdbc:mysql://127.0.0.1:3306/xpay?useUnicodetruecharacterEncodingutf8useSSLfalse \ --spring.datasource.usernamexpay_user \ --spring.datasource.passwordxpay_pass_2025启动顺序有讲究先 server 后 monitor。因为 monitor 起来的第一件事是扫描订单表把之前已支付但还没回调成功的订单重新放入回调队列这个补扫逻辑依赖数据库和回调组件server 没起来的话它扫到了也投递不出去。看到 server 日志里 Tomcat started on port 8080 之后再启动 monitor。monitor 正常启动的日志特征是有类似monitor connected或listening for payment notification的输出。如果只看到 Spring 的 Banner 就结束说明它没连上监听通道后面排查会非常难受。我建议本地验证时两个进程都在前台跑日志直接打到终端链路哪里断了扫一眼就能定位。3.4 验证链路curl 下单、扫码支付、观察回调服务起来了完整验证要跑通一整条链路。先在业务侧准备一个测试回调接口或者用能收 POST 的工具临时监听然后向 XPay 发起下单curl -X POST http://127.0.0.1:8080/api/order/create \ -H Content-Type: application/json \ -d {merchant_id:M2024001,amount:1.00,notify_url:http://127.0.0.1:9000/xpay/callback}正常响应长这样重点在data里的pay_text和qr_content{ code: 0, message: ok, data: { order_no: XP202501200001, pay_text: 扫码付款备注填 XP202501200001, qr_content: https://qr.alipay.com/xxx, expire_seconds: 600 } }qr_content是收款码的原始内容用 ZXing 或任意二维码工具转成图片pay_text会提示用户付款时备注订单号。然后扫码支付 1 元付款成功后 1 到 3 秒内monitor 日志会打印解析到的金额和备注订单状态从 0 变 1如果回调地址可达业务侧几秒内收到 POST 回调。链路走到这一步部署就算完整验证过了。提示自测金额不要搞大1 元足够验证链路验证完去管理后台把测试单关闭避免后续统计里混入测试数据。4. 避坑指南XPay 部署与使用中的五个高频翻车点下面是我实际部署中按频率排序的五条问题每条都按现象、原因、解决的思路写可以直接拿来对照排查。4.1 付款后订单一直「待支付」先查 monitor再查金额现象用户明确说已经扫码付款了管理后台订单状态却一直停在 0业务系统自然也没收到回调。原因排查优先级最高的是 monitor 进程。V3.1 的 notify 策略依赖 monitor 挂在收款账号的支付客户端或通知通道上monitor 没起来、设备离线、通知通道被系统切断到账事件就根本不会进到 XPay。其次是金额对不上订单金额 10 元实际到账 9.95 元XPay 拿 9.95 去匹配 10.00 的待支付订单匹配失败订单保持原样。个人收款场景里手续费、用户少付几分钱都是常见误差来源。解决第一步看 monitor 日志有没有解析到新的到账事件没有就先把监听链路修好。第二步对比到账金额与订单金额的差异。如果业务能接受手续费损耗就在下单时把手续费按比例算进订单金额或者在配置里打开金额容差开关。这个开关源码里有默认关闭打开后可以容忍指定金额误差但会略微降低匹配精度建议只在固定金额场景使用。4.2 回调收不到notify_url 可达性与重试耗尽现象订单状态已经从 0 变成 1但业务系统侧完全没有收到回调的日志。原因notify_url填的是内网地址或者 localhostXPay 跑在公网服务器上根本访问不到你的本机另一个常见原因是回调接口处理逻辑太重XPay 在 5 秒内没收到 HTTP 200 就判定失败重试次数耗尽后同样放弃。解决生产环境回调地址必须是公网可访问的 HTTPS 接口回调接口处理要轻量收到通知先返回 success再异步去处理发货。排查时打开管理后台的回调记录看notify_count和notify_msg。如果notify_msg显示连接超时说明是网络问题如果显示业务状态码说明接口已收到但在业务逻辑里被拦了。notify_msg是整个回调链路里信息量最大的字段没有之一。4.3 回调验签失败多半是 secret 两边不一致现象回调记录里业务系统持续返回 401 或「签名错误」重试次数白白耗尽。原因最常见的只有一种——XPay 配置的 secret 和业务系统里保存的 secret 不一致。部署时两边各配各的看起来都改了但一个是默认值change_me另一个是自定义值两边对不上。其次是在二次开发时自己改了签名算法或参数拼接顺序。解决先核验 secret 字符串完全一致再把两边签名原文打印出来逐字符对比。源码里签名工具类通常叫 SignUtil 或 SignatureUtil拼接顺序以这个类为准不要自己按 JSON 字段顺序拼。有些人在业务系统里直接把收到的 JSON 字符串拿来做摘要XPay 是按参数名排序后拼成 query string 再做 HMAC-SHA256两边规则不同验签必然失败。检查时顺手确认大小写十六进制签名统一转小写比较大小写不一致也会误判。4.4 相同金额订单匹配串单双因子匹配是底线现象两笔 100 元订单同时在池子里只收到一笔 100 元到账XPay 把 A 订单标记成已支付但用户实际付的是 B 订单。原因匹配规则是金额加备注双因子。如果下单流程没把备注必填打开用户付款时没填备注XPay 只能按金额去池子里找遇到多笔相同金额的待支付订单就只能碰运气。解决第一下单时把备注必填打开并把备注设计成固定前缀加短随机码比如P8K3A2让备注具备唯一性。第二业务系统在回调里校验订单号和金额要同时匹配防止 XPay 把订单匹配错了之后业务侧也跟着错。第三匹配失败的订单一律落到「待人工确认」状态不要自动选一个最接近的。自动发货场景里串单造成的损失可能要自己来赔人工确认虽然慢一点但至少不会错。4.5 重启后已支付订单不再回调启动补扫是后悔药现象升级版本或重启服务器之后有几笔订单状态停在 1一直没有走到 2业务系统也没收到通知。原因XPay 的回调队列在进程内存里重启即丢失。订单状态已经更新到 1但回调还没来得及发出这些订单就静静躺在数据库里没人管。解决在启动阶段做一次补扫查出所有status1且notify_count小于重试上限的订单重新塞回回调队列。这个逻辑放在 ApplicationRunner 里启动完成后自动执行十几行代码就能搞定。补扫完成会打印一行类似scan unhandled orders: 3的日志。重启之后一定要检查这行日志看到数字再对外确认服务恢复不然就还有几笔订单在裸奔。5. 二次开发要点回调验签与订单状态机设计5.1 验签逻辑先排序拼接再做 HMAC-SHA256业务系统收到回调后不能直接更新订单正确顺序应该是验签、查订单、幂等判断、金额校验、更新状态、发货。验签时注意签名原文不是 JSON 原文而是把回调参数去掉sign后按参数名排序、再拼成 query string。这一步错了签永远对不上。public boolean verifySign(MapString, String params, String secret) { String sign params.remove(sign); String raw params.entrySet().stream() .filter(e - e.getValue() ! null e.getValue().length() 0) .sorted(Map.Entry.comparingByKey()) .map(e - e.getKey() e.getValue()) .collect(Collectors.joining()); String expected hmacSha256(secret, raw); return expected.equalsIgnoreCase(sign); }逻辑说明先把回调参数里的 sign 摘掉剩余参数按 key 排序拼成merchant_idxxxorder_noxxxamountxxxtimestampxxx这样的原始字符串再用 secret 做 HMAC-SHA256 得到期望签名。最后跟回调传过来的 sign 忽略大小写比较。参数排序是字典序用comparingByKey保证别自己手写排序容易漏字段。验签通过后必须核对金额是否与本地订单一致。这一步很多人会漏漏掉的结果是攻击者拿一笔 1 元订单的回调串去改金额业务系统如果只看订单号不看金额就可能把大额订单免单属于一等一的安全事故。金额比较要用compareTo不要用equalsBigDecimal 的equals会同时比较精度。5.2 回调处理用订单状态实现幂等回调网络不可靠XPay 重试导致同一个回调多次到达业务侧必须做幂等。最简单做法是状态判断订单已经从待支付走到已支付了再收到重复回调直接返回 success不重复发货。if (order.getStatus() PayStatus.CALLBACKED) { return success; }在 Spring Boot 里接回调就是加一个 Controller把验签和状态判断串起来确认通过后再去调自己的订单服务走发货流程。回调接口的响应要么 returnsuccess要么抛异常让 XPay 重试。不要把带业务含义的 JSON 也返回 200XPay 把非success的响应记录到notify_msg一旦你返回了带业务错误码却是 200 的 JSONXPay 会认为回调成功订单状态置为 2业务侧独自失败这种情况最不好排查。5.3 把 XPay 接进业务系统的最小改动接入时我习惯固定写一个XPayCallbackController专门接收 XPay 的回调里面只做三件事验签、幂等、金额校验。这三步全部通过后把内部订单号映射到自己的业务订单再触发自己的订单状态机。从那以后我每次接入回调接口都强制自己把验签、幂等、金额校验这三行步骤放在所有业务逻辑之前顺序固定下来踩坑的概率就低很多。希望这篇笔记能帮到你。本文还有配套的精品资源点击获取