简介四方支付源码是一套基于ThinkPHP框架开发的企业级PHP第三方API支付系统面向需要快速接入支付宝、微信、银联等多种渠道的商家、平台运营方及二次开发人员。压缩包共2000个文件以849个PHP核心程序文件为主搭配HTML、JS、CSS等前端交互资源以及大量GIF、PNG、JPG等界面素材和DAT、LOG等运行数据文件整体约47.73MB目录层次清晰便于定位支付接口、控制器与模板。该商业版提供支付接口集成、商户注册与认证、订单自动化处理、资金结算、风险控制等完整模块并附有API文档、多语言支持文件与安全校验配置开发者可基于其扩展定制。已有2656人学习下载对搭建四方支付平台、理解聚合支付流程或研究ThinkPHP框架实战均有直接参考价值。1. 四方支付源码究竟是什么从支付链路看懂它解决什么问题四方支付源码是一套把微信、支付宝、银联等多种支付通道聚合到同一个后台的工程代码。做过电商或 SaaS 的朋友大多有这种体感每个渠道一套 API签名方式不一样、回调机制不一样、对账文件格式也不一样商户侧要同时维护好几套逻辑账差一出现根本不知道去哪里查。四方支付源码解决的就是这件事它用统一接口承接商户背后通过路由策略把支付请求分发到不同通道同时把订单管理、资金结算、对账、分账这些平台侧能力一起沉淀下来。它适合正在做聚合支付产品、需要对接多个支付渠道的中后台研发团队也适合想理解支付系统设计的人。不过有一点必须前置说明四方支付直接参与资金流转技术之外有严格资质要求这篇只讲工程实现商用前请先确认自己的合规边界。2. 四方支付的四方模型与资金流向动手写码前必须先立住的业务边界2.1 四方支付链路拆解四个参与方分别承担什么职责三方支付是支付机构直接服务商户四方支付多出一个四方平台。所谓四方第一方是付款人也就是消费者第二方是收款商户第三方是真正握有支付牌照的通道方比如微信、支付宝、银联第四方就是聚合平台本身。四方平台不直接碰持卡人的卡号信息也不自己有清算资格它做的事情在技术上是「聚合」与「转发」商户只需要对接四方平台的一套 API由平台按规则选择底层通道。一次典型的四方支付请求链路可以这样描述用户在商户应用里发起支付商户系统调四方平台的下单接口四方平台按渠道路由配置选择一个通道返回该通道的收银台地址或支付参数用户完成支付后通道通过异步通知把结果告诉四方平台四方平台校验签名后更新内部订单再通知商户系统。日终四方平台从通道拉取对账单与自己库里的支付流水做比对差异数据进差错处理最后按结算周期给商户生成结算单。# 支付状态机枚举理解整个流程的状态变化 PAYMENT_STATUS { 0: 支付中, 1: 支付成功, 2: 支付失败, 3: 已关闭, 4: 已退款, 5: 对账差异, }逻辑说明这段伪代码把订单流程里的状态枚举先定下来。四方支付所有代码都围绕这套状态流转尤其是「支付中」到「支付成功」的切换靠的是回调通知而不是用户主动查询。参数说明0 和 3 的差异在于超时主动关单5 只在日终对账时出现正常情况下不应存在。这条路线的价值在于商户只需要维护一个接口对接通道的个性化逻辑被收敛在平台侧。对于平台研发来说必须把通道差异隔离在独立模块里才能避免「改一个通道影响全部商户」的失控局面。常见的做法是定义一个统一的渠道接口每个通道实现一套适配器业务层只依赖统一接口。2.2 资金结算与账务模型为什么说四方支付是技术加资金的双重工程资金实际流向是消费者支付的钱先进通道通道在约定时间把资金结算给四方平台在通道侧开立的账户四方平台再扣除手续费、分账金额后结算给商户。这个过程中四方平台相当于先归集资金再分发所以在技术上必须做到每一分钱都有流水可查。很多团队拿到四方支付源码后第一件事就是写业务代码结果账目对不上根源就是没有先建立账务表模型。我用一个简化但完整的账务模型来说明至少需要三张表支付流水表、商户结算表、渠道对账单表。支付流水表记录每一笔交易的明细商户结算表记录每个结算周期给商户打款的汇总渠道对账单表存放原始对账单数据。-- 支付流水表四方平台内部每一笔订单的核心记录 CREATE TABLE t_payment_order ( id BIGINT AUTO_INCREMENT PRIMARY KEY, merchant_code VARCHAR(32) NOT NULL COMMENT 商户编号, out_trade_no VARCHAR(64) NOT NULL COMMENT 商户订单号, pay_order_no VARCHAR(64) NOT NULL COMMENT 平台内部订单号, channel_code VARCHAR(16) NOT NULL COMMENT 通道编码 wechat/alipay/unionpay, channel_trade_no VARCHAR(64) COMMENT 通道交易号, total_amount INT NOT NULL COMMENT 订单金额单位分, channel_fee INT DEFAULT 0 COMMENT 通道手续费单位分, platform_fee INT DEFAULT 0 COMMENT 平台服务费单位分, settle_amount INT DEFAULT 0 COMMENT 商户结算金额单位分, status TINYINT NOT NULL COMMENT 0支付中 1成功 2失败 3关闭 4退款, notify_status TINYINT DEFAULT 0 COMMENT 商户通知状态 0待通知 1成功 2失败, create_time DATETIME NOT NULL, update_time DATETIME NOT NULL, UNIQUE KEY uk_pay_order_no (pay_order_no), UNIQUE KEY uk_merchant_out_trade_no (merchant_code, out_trade_no) ) COMMENT 支付流水表;逻辑说明表结构里最关键的是两个唯一索引。pay_order_no保证平台内部单号唯一uk_merchant_out_trade_no保证同一个商户的同一个订单号不能重复这是回调幂等的基础。金额字段全部用 int 类型的分不要用浮点数否则对账时会出现 0.1 加 0.2 不等于 0.3 的小数误差。channel_fee和platform_fee在支付成功后由平台的费率和协议自动计算settle_amount等于total_amount减去两个费用字段这个字段会在生成结算单时被引用。-- 商户结算表按结算周期汇总给商户打款 CREATE TABLE t_merchant_settlement ( id BIGINT AUTO_INCREMENT PRIMARY KEY, settlement_no VARCHAR(32) NOT NULL COMMENT 结算单号, merchant_code VARCHAR(32) NOT NULL COMMENT 商户编号, settle_amount INT NOT NULL COMMENT 结算金额单位分, total_count INT NOT NULL COMMENT 交易笔数, status TINYINT NOT NULL COMMENT 0待审核 1待打款 2已打款 3失败, begin_time DATETIME NOT NULL, end_time DATETIME NOT NULL, create_time DATETIME NOT NULL, UNIQUE KEY uk_settlement_no (settlement_no) ) COMMENT 商户结算表;参数说明结算表里要保留begin_time和end_time因为结算周期不是按自然月硬算的而是按订单成功的实际时间范围汇总这样既支持 T1 也支持自定义周期。status字段从待审核到已打款的状态流转需要财务人工介入不能全自动否则打款出去再发现账务问题后悔药很难吃。有了这两张表四方支付的资金视角就立住了。接下来所有代码都围绕「支付流水如何产生、如何被更新、如何被汇总」展开。所以我的习惯是拿到任何一套四方支付源码先不看业务接口先看数据库脚本里的表设计只要三张核心表的字段和状态机清楚了整个源码的架构就清楚了一半。3. 基于四方支付源码二次开发的落地路径从源码包到最小可用工程3.1 拿到源码包后的目录结构先分清聚合层与通道层假设你手头有一套典型的四方支付源码包解压后先别急着启动先看目录。常见做法是 Maven 或 Gradle 多模块工程因为聚合支付天生需要把核心模型、通道适配、后台管理、对外网关分离出来。我见过很多把它直接做成单应用的老项目一旦接入新通道核心代码被渠道 SDK 塞满最终只能推倒重来。tar -xzf pay4x-source.tar.gz cd pay4x tree -L 2 -d模拟输出pay4x ├── pay4x-common # 公共工具类、常量、统一返回模型 ├── pay4x-core # 核心业务逻辑订单服务、路由、账务 ├── pay4x-channel # 通道适配层 │ ├── pay4x-channel-wechat # 微信支付适配器 │ ├── pay4x-channel-alipay # 支付宝适配器 │ └── pay4x-channel-unionpay # 银联适配器 ├── pay4x-gateway # 对外 HTTP 网关商户接入层 ├── pay4x-admin # 运营后台商户管理、结算审核 └── pay4x-job # 定时任务日终对账、关单、结算逻辑说明pay4x-channel这一层是最重要的隔离带。每个通道适配器只允许依赖该通道的 SDK 和 pay4x-common不能依赖核心业务代码。这样新增一个通道时核心层完全不改动只是在路由配置里多注册一个实现。pay4x-job单独拎出来是对账和结算这类定时任务的正确打开方式否则在后台进程里跑调度时间一长会出现任务重复执行和内存溢出问题。3.2 配置数据库与支付渠道参数沙箱环境里的最小可跑通配置最小工程先不要接真实商户和真实密钥把沙箱参数跑通更重要。源码自带一套参考配置通常放在pay4x-core/src/main/resources/application.yml下面。我一般先改四个位置数据库连接、Redis、回调域名、通道沙箱开关。spring: datasource: url: jdbc:mysql://localhost:3306/pay4x?useSSLfalsecharacterEncodingutf8 username: pay4x password: changeit redis: host: localhost port: 6379 database: 0 pay4x: # 对外回调域名通道回调与商户通知都会拼上这个域名 notify-domain: https://api.example.com # 渠道路由默认超时时间单位毫秒 route-timeout: 3000 channels: wechat: enabled: true sandbox: true app-id: wx_demo_app_id mch-id: 10000001 api-key: ${WECHAT_API_KEY} cert-path: /data/certs/wechat/apiclient_cert.p12 alipay: enabled: true sandbox: true app-id: 2021000000000000 private-key: ${ALIPAY_PRIVATE_KEY} alipay-public-key: ${ALIPAY_PUBLIC_KEY} sign-type: RSA2 unionpay: enabled: false mer-id: unionpay_test_mer cert-path: /data/certs/unionpay/unionpay.pfx参数说明notify-domain是全站最容易配错的地方回调地址必须是对外可访问的 HTTPS 域名不能是 IP 或内网地址也不能是 1.1.1.1 这种替换占位否则通道的异步通知发不过来订单永远停在「支付中」。route-timeout是平台向上游通道发起请求的最长时间3 秒是很多团队的默认值太短容易碰到通道抖动误判失败太长会让用户在支付页等待过久。密钥部分不要直接写在 yml 里用${WECHAT_API_KEY}这类环境变量引用私钥文件路径单独放在不分发的目录这是很多源码 demo 里没做好的事。配置完成后启动顺序是先起 pay4x-job 里的基础定时任务依赖再起 pay4x-gateway。启动后先调用健康检查接口比如GET /actuator/health确认数据库和 Redis 都正常连接。然后进入管理后台创建一个测试商户拿到商户编号和签名密钥就可以开始跑一笔沙箱支付。注意沙箱环境里微信和支付宝的回调地址往往不进公网需要靠后台的模拟回调工具触发这一步等到了回调处理模块再详细说。4. 四方支付源码核心模块精读下单、回调、对账的三段关键代码4.1 下单接口策略模式是把多通道差异揉进同一段逻辑的关键四方支付源码里最常被自定义改造的就是下单接口。商户通过网关发送一个下单请求里面包含账单金额、支付方式、商户订单号平台要根据channelCode找到对应通道的适配器再返回通道要求的支付参数。直接用if (channelCode.equals(wechat))写当然能跑但每加一个通道就要改一次核心方法所以源码里更常见的做法是策略模式配合 Spring 的依赖注入。Component public class UnifiedOrderService { private final MapString, ChannelRouter routerMap; public UnifiedOrderService(ListChannelRouter routers) { // Spring 会把所有 ChannelRouter 实现注入进来key 由每个实现自己声明 this.routerMap routers.stream() .collect(Collectors.toMap(ChannelRouter::channelCode, Function.identity())); } public PayOrderResult createOrder(OrderCreateRequest request) { // 1. 基础校验商户是否存在、金额是否大于0 Merchant merchant merchantService.validAndGet(request.getMerchantCode()); if (merchant null) { throw new BizException(MERCHANT_NOT_FOUND); } // 2. 生成平台内部唯一单号格式可以带日期和随机数 String payOrderNo generatePayOrderNo(); // 3. 根据请求里的 channelCode 选择适配器未命中直接报错 ChannelRouter router routerMap.get(request.getChannelCode()); if (router null) { throw new BizException(CHANNEL_NOT_SUPPORTED); } // 4. 调用适配器下单这里只依赖统一接口 ChannelPlaceOrderResult result router.placeOrder(buildChannelRequest(request, payOrderNo)); // 5. 下单成功后保存支付流水状态为支付中 paymentOrderService.savePendingOrder(payOrderNo, request, result.getChannelTradeNo()); return PayOrderResult.success(payOrderNo, result.getPayParams()); } }逻辑说明routerMap的 key 是channelCode字符串value 是每个通道的具体实现所以新增通道时只需要增加一个实现类并注册成 Spring Bean。buildChannelRequest会把商户的原始请求转成各通道需要的格式这一步即使放在统一方法里也建议用接口隔离不要直接暴露给上层。generatePayOrderNo建议用「时间戳 商户号 随机数」而不是纯自增因为支付单号可能会出现在对账单和回调日志里纯自增容易被人推测出平台交易量。参数说明ChannelPlaceOrderResult至少要有三个字段——通道交易号、通道返回的支付参数可能是收银台 URL 或 SDK 请求参数、是否立即成功比如小额免密场景。沙箱调试时重点看router.placeOrder内部打出的请求日志通常源码里会预留log.debug(wechat place order request: {}, request)这样的输出把开关打开可以省下很多抓包时间。4.2 回调处理幂等性与签名校验两层保护缺一不可回调处理是四方支付里最容易出生产事故的代码。通道的回调通知可能因为网络抖动重复推送也可能在极端情况下延迟几小时才到。如果回调处理不是幂等的商户订单状态被二次更新金额可能重复入账这对资金安全是致命的。源码里通常会用数据库唯一索引加应用层锁来兜底。Component public class NotifyService { private final PaymentOrderMapper orderMapper; private final IdempotentLockService idempotentLock; public String handleChannelNotify(ChannelNotify notify) { // 1. 验签不通过直接返回失败让通道继续重推 boolean verified channelSignService.verifySign(notify.getChannelCode(), notify.getRawData()); if (!verified) { log.warn(notify sign invalid, channel{}, notify.getChannelCode()); return FAILURE; } // 2. 按通知 ID 做幂等存在则直接返回成功不再处理 if (!idempotentLock.tryLock(notify: notify.getNotifyId(), 10)) { return SUCCESS; } // 3. 查询内部订单确认当前状态只有支付中才更新 PaymentOrder order orderMapper.findByPayOrderNo(notify.getPayOrderNo()); if (order null || order.getStatus() ! PAYMENT_STATUS_PENDING) { return SUCCESS; } // 4. 更新订单为成功并记录通道交易号和手续费 orderMapper.markSuccess(order.getId(), notify.getChannelTradeNo(), notify.getChannelFee()); // 5. 触发对商户的异步通知通知失败则等待定时任务补偿 merchantNotifyService.push(order.getMerchantCode(), order.getOutTradeNo()); return SUCCESS; } }逻辑说明第 2 步的tryLock用的是 RedisSETNX加过期时间过期时间设置为 10 秒足够覆盖一次回调处理耗时即使处理进程宕机锁也会自动释放。第 3 步的「只有支付中才更新」是第二层幂等保护因为数据库更新本身就不是重复安全的业务上要求一次订单只能从待支付变成成功。第 5 步商户通知必须做成异步队列加失败重试渠道的回调超时时间很短如果在通知商户上卡太久通道会认为平台没有正确接收回调。参数说明notify.getChannelFee()在有些通道的沙箱环境里是空值或字符串落库前要先做空值转 0 和金额单位的统一转换。我见过的翻车案例是通道返回以元为单位的字符串内部表存的是分直接落库后整张表的对账金额全部少了 100 倍。所以回调处理里必须有一层金额单位转换用工具类统一为整数分。4.3 对账文件解析把通道侧的对账单转成平台侧可核对的差异明细日终对账是四方支付源码里最琐碎但也最能体现干脆利落的模块。通道每天生成一个原始对账单文件可能是 CSV、Excel 或类 JSON里面包含当天的交易明细、手续费、退款记录。平台要做的是把这个文件和自己库里的支付流水比对生成金额不一致或者双方单边订单的差异列表。# 以某通道的 CSV 对账单为例解析并与内部流水比对 import csv import pymysql channel_file /data/check/wechat_20250301.csv internal_orders {} conn pymysql.connect(hostlocalhost, userpay4x, passwordchangeit, databasepay4x) with conn.cursor() as cursor: cursor.execute(SELECT pay_order_no, total_amount, status FROM t_payment_order WHERE create_time %s, (2025-03-01 00:00:00,)) for row in cursor.fetchall(): internal_orders[row[0]] {amount: row[1], status: row[2]} diff_list [] with open(channel_file, r, encodingutf-8) as fp: reader csv.DictReader(fp) for row in reader: channel_trade_no row[商户单号].strip() channel_amount int(round(float(row[交易金额]) * 100)) inner internal_orders.get(channel_trade_no) if inner is None: diff_list.append({trade_no: channel_trade_no, type: 渠道单边, amount: channel_amount}) elif inner[amount] ! channel_amount: diff_list.append({trade_no: channel_trade_no, type: 金额不一致, amount_diff: channel_amount - inner[amount]}) elif inner[status] ! 1: diff_list.append({trade_no: channel_trade_no, type: 平台未成功, amount: channel_amount}) else: internal_orders.pop(channel_trade_no, None) # 内部有但渠道没有的订单属于平台单边 for trade_no, order in internal_orders.items(): if order[status] 1: diff_list.append({trade_no: trade_no, type: 平台单边, amount: order[amount]}) for diff in diff_list: print(diff)逻辑说明这段脚本先把平台内部的支付流水加载到内存字典里然后逐行读通道对账单比对。channel_amount的转换是关键对账单常见单位是元而且有小数点误差用round(float(x) * 100)转成整数分比直接用int(float(x))更稳。单边差异是指只有一方有记录需要人工核实。参数说明比对时不要用过大的时间范围建议按单日或单小时批量处理否则内存字典可能被积年数据撑爆。5. 四方支付源码二次开发避坑手册资金安全与并发场景的五个常见问题5.1 回调重复通知导致订单金额被翻倍更新现象一笔订单收到两次回调第二次回调把订单状态又从成功更新成了成功触发商户通知被推了两次商户侧库存被扣减两次。原因回调处理只判断了order ! null没有判断当前状态是不是支付中或者幂等锁的 key 用了订单号而不是通知 ID同一笔订单的多次通知共用一把锁锁过期后第二次回调继续往下走。解决把幂等锁的 key 换成notify.getNotifyId()同时在数据库更新语句里加状态条件比如UPDATE t_payment_order SET status 1 WHERE id #{id} AND status 0让数据库层拒绝重复更新。两层保护缺一不可应用层锁防并发数据库条件更新防串行。5.2 各通道签名算法不一致导致验签失败现象接入支付宝时回调验签通过接入微信时同样逻辑一直报验签失败排查发现大版本升级后 1 个通道换了新签名类型。原因不同通道的签名算法有 MD5、HMAC-SHA256、RSA2 甚至国密 SM2即使算法名称一致签名内容构造规则也完全不同。很多源码把验签逻辑直接写死在回调方法里换通道就要改核心代码。解决在通道适配器内部各自实现验签逻辑对外提供统一verifySign接口。增加通道时把该通道官方 SDK 的验签方法封装在适配器里核心业务不感知差异。遇到验签失败先打开调试日志看原始报文和参与签名的字段列表通常能排查出拼参顺序错误或字段遗漏。5.3 对账差异集中在退款订单上金额总是算不平现象日终对账脚本跑完退款订单几乎全部报「金额不一致」且差异金额恰好等于退款金额。原因对账单上退款和支付是同一行字段用交易类型区分而内部表里退款订单单独存了退款流水金额字段记录的是原始支付金额比对时拿原金额去比对退款行当然差一倍。解决先把对账单按交易类型拆分支付单比对支付流水退款单比对退款流水。退款单金额方向为负取绝对值后与内部退款表中的金额比对。同时检查平台侧是否把退款状态单独建立了t_refund_order表不要让退款流水混进支付流水表。5.4 下单接口并发压测时出现重复平台单号现象压测跑到每秒 500 个事务时数据库偶尔报唯一键冲突日志里能看到同一个payOrderNo被重复创建。原因生成单号的逻辑用了「时间戳 随机数」在高并发下时间戳粒度只有毫秒随机数随机范围有限导致碰撞概率上升单体应用里同步生成没问题部署多实例后冲突概率成倍增加。解决单号生成组件改用「雪花算法」或「号段模式」至少要保证跨进程唯一。如果源码用的是数据库自增每个实例单独每次插入会导致锁竞争建议独立一个序列表或引入 Redis 的 INCR把单号生成做成独立服务。5.5 商户回调通知失败后没有补偿机制订单支付成功但用户没收到通知现象某次通道大面积超时导致回调线程池阻塞商户回调消息积压最终消息丢失用户支付成功但商户系统没有收到同步通知只能靠用户主动查询。原因回调处理里把商户通知做成同步调用一旦商户接口响应慢线程池被占满后续通知全部排队时间一长丢弃。更糟的是没有本地消息表通知失败后没有重试入口。解决引入本地消息表回调更新订单状态后先把「待通知」记录写入t_merchant_notify_task再由独立线程扫描推送推送失败标记状态定时任务按指数退避重试。重试次数上限设 5 次超过后进人工告警。这套逻辑在做四方支付时几乎是标配没有补偿机制的生产环境早晚会出事故。6. 让四方支付源码真正可用三个进阶加固建议与验证方法第一把支付结果从依赖回调改成依赖「回调 主动查询」双向确认。通道的回调不是可靠交付会丢也会被阻塞正确的做法是在回调更新成功后再向通道发起一次主动订单查询比对两边状态。查询接口通常有频率限制所以控制在一笔订单最多主动查询两次一次在回调后 10 秒一次在回调后 5 分钟。第二给核心账务字段加防篡改校验。支付流水表里的金额、手续费、结算字段建议增加一个校验列保存这些字段的摘要值比如用 SHA-256 计算整行关键字段的结果。每天结算跑批前先做一遍完整性校验一旦发现某行数据被非法修改立刻阻断结算流程。对普通业务系统这可能是过度设计但对四方支付这种涉及真金白银的系统多一道防线好过事后追账。第三做一次全链路的渠道故障演练。选一个周末低峰期在沙箱环境模拟某通道 30 分钟完全不可用验证平台的路由切换逻辑能否自动把新订单切到备用通道存量支付中的订单能否在恢复后正常回调。演练结束后检查「支付中」状态超过 24 小时的订单确认关单任务有没有把超时订单全部关掉。这套演练的价值在于不需要等真实通道故障时才开始手忙脚乱地看日志。验证方法也很直接从商户后台发起一笔 0.01 元支付支付成功后到平台后台确认支付流水是成功状态再等到次日对账单生成后跑一遍对账脚本确认没有任何差异记录。反复跑通这个闭环说明这套源码在你的环境里是真的能用的而不是只启动成功。我的习惯是把这个验证脚本写成集成测试用例每次升级代码后先跑一遍再发版。四方支付的核心就一句话钱走哪里代码就要跟到哪里。希望这篇文章能帮你少踩一些坑愿你的账永远对得上。本文还有配套的精品资源点击获取
简介四方支付源码是一套基于ThinkPHP框架开发的企业级PHP第三方API支付系统面向需要快速接入支付宝、微信、银联等多种渠道的商家、平台运营方及二次开发人员。压缩包共2000个文件以849个PHP核心程序文件为主搭配HTML、JS、CSS等前端交互资源以及大量GIF、PNG、JPG等界面素材和DAT、LOG等运行数据文件整体约47.73MB目录层次清晰便于定位支付接口、控制器与模板。该商业版提供支付接口集成、商户注册与认证、订单自动化处理、资金结算、风险控制等完整模块并附有API文档、多语言支持文件与安全校验配置开发者可基于其扩展定制。已有2656人学习下载对搭建四方支付平台、理解聚合支付流程或研究ThinkPHP框架实战均有直接参考价值。1. 四方支付源码究竟是什么从支付链路看懂它解决什么问题四方支付源码是一套把微信、支付宝、银联等多种支付通道聚合到同一个后台的工程代码。做过电商或 SaaS 的朋友大多有这种体感每个渠道一套 API签名方式不一样、回调机制不一样、对账文件格式也不一样商户侧要同时维护好几套逻辑账差一出现根本不知道去哪里查。四方支付源码解决的就是这件事它用统一接口承接商户背后通过路由策略把支付请求分发到不同通道同时把订单管理、资金结算、对账、分账这些平台侧能力一起沉淀下来。它适合正在做聚合支付产品、需要对接多个支付渠道的中后台研发团队也适合想理解支付系统设计的人。不过有一点必须前置说明四方支付直接参与资金流转技术之外有严格资质要求这篇只讲工程实现商用前请先确认自己的合规边界。2. 四方支付的四方模型与资金流向动手写码前必须先立住的业务边界2.1 四方支付链路拆解四个参与方分别承担什么职责三方支付是支付机构直接服务商户四方支付多出一个四方平台。所谓四方第一方是付款人也就是消费者第二方是收款商户第三方是真正握有支付牌照的通道方比如微信、支付宝、银联第四方就是聚合平台本身。四方平台不直接碰持卡人的卡号信息也不自己有清算资格它做的事情在技术上是「聚合」与「转发」商户只需要对接四方平台的一套 API由平台按规则选择底层通道。一次典型的四方支付请求链路可以这样描述用户在商户应用里发起支付商户系统调四方平台的下单接口四方平台按渠道路由配置选择一个通道返回该通道的收银台地址或支付参数用户完成支付后通道通过异步通知把结果告诉四方平台四方平台校验签名后更新内部订单再通知商户系统。日终四方平台从通道拉取对账单与自己库里的支付流水做比对差异数据进差错处理最后按结算周期给商户生成结算单。# 支付状态机枚举理解整个流程的状态变化 PAYMENT_STATUS { 0: 支付中, 1: 支付成功, 2: 支付失败, 3: 已关闭, 4: 已退款, 5: 对账差异, }逻辑说明这段伪代码把订单流程里的状态枚举先定下来。四方支付所有代码都围绕这套状态流转尤其是「支付中」到「支付成功」的切换靠的是回调通知而不是用户主动查询。参数说明0 和 3 的差异在于超时主动关单5 只在日终对账时出现正常情况下不应存在。这条路线的价值在于商户只需要维护一个接口对接通道的个性化逻辑被收敛在平台侧。对于平台研发来说必须把通道差异隔离在独立模块里才能避免「改一个通道影响全部商户」的失控局面。常见的做法是定义一个统一的渠道接口每个通道实现一套适配器业务层只依赖统一接口。2.2 资金结算与账务模型为什么说四方支付是技术加资金的双重工程资金实际流向是消费者支付的钱先进通道通道在约定时间把资金结算给四方平台在通道侧开立的账户四方平台再扣除手续费、分账金额后结算给商户。这个过程中四方平台相当于先归集资金再分发所以在技术上必须做到每一分钱都有流水可查。很多团队拿到四方支付源码后第一件事就是写业务代码结果账目对不上根源就是没有先建立账务表模型。我用一个简化但完整的账务模型来说明至少需要三张表支付流水表、商户结算表、渠道对账单表。支付流水表记录每一笔交易的明细商户结算表记录每个结算周期给商户打款的汇总渠道对账单表存放原始对账单数据。-- 支付流水表四方平台内部每一笔订单的核心记录 CREATE TABLE t_payment_order ( id BIGINT AUTO_INCREMENT PRIMARY KEY, merchant_code VARCHAR(32) NOT NULL COMMENT 商户编号, out_trade_no VARCHAR(64) NOT NULL COMMENT 商户订单号, pay_order_no VARCHAR(64) NOT NULL COMMENT 平台内部订单号, channel_code VARCHAR(16) NOT NULL COMMENT 通道编码 wechat/alipay/unionpay, channel_trade_no VARCHAR(64) COMMENT 通道交易号, total_amount INT NOT NULL COMMENT 订单金额单位分, channel_fee INT DEFAULT 0 COMMENT 通道手续费单位分, platform_fee INT DEFAULT 0 COMMENT 平台服务费单位分, settle_amount INT DEFAULT 0 COMMENT 商户结算金额单位分, status TINYINT NOT NULL COMMENT 0支付中 1成功 2失败 3关闭 4退款, notify_status TINYINT DEFAULT 0 COMMENT 商户通知状态 0待通知 1成功 2失败, create_time DATETIME NOT NULL, update_time DATETIME NOT NULL, UNIQUE KEY uk_pay_order_no (pay_order_no), UNIQUE KEY uk_merchant_out_trade_no (merchant_code, out_trade_no) ) COMMENT 支付流水表;逻辑说明表结构里最关键的是两个唯一索引。pay_order_no保证平台内部单号唯一uk_merchant_out_trade_no保证同一个商户的同一个订单号不能重复这是回调幂等的基础。金额字段全部用 int 类型的分不要用浮点数否则对账时会出现 0.1 加 0.2 不等于 0.3 的小数误差。channel_fee和platform_fee在支付成功后由平台的费率和协议自动计算settle_amount等于total_amount减去两个费用字段这个字段会在生成结算单时被引用。-- 商户结算表按结算周期汇总给商户打款 CREATE TABLE t_merchant_settlement ( id BIGINT AUTO_INCREMENT PRIMARY KEY, settlement_no VARCHAR(32) NOT NULL COMMENT 结算单号, merchant_code VARCHAR(32) NOT NULL COMMENT 商户编号, settle_amount INT NOT NULL COMMENT 结算金额单位分, total_count INT NOT NULL COMMENT 交易笔数, status TINYINT NOT NULL COMMENT 0待审核 1待打款 2已打款 3失败, begin_time DATETIME NOT NULL, end_time DATETIME NOT NULL, create_time DATETIME NOT NULL, UNIQUE KEY uk_settlement_no (settlement_no) ) COMMENT 商户结算表;参数说明结算表里要保留begin_time和end_time因为结算周期不是按自然月硬算的而是按订单成功的实际时间范围汇总这样既支持 T1 也支持自定义周期。status字段从待审核到已打款的状态流转需要财务人工介入不能全自动否则打款出去再发现账务问题后悔药很难吃。有了这两张表四方支付的资金视角就立住了。接下来所有代码都围绕「支付流水如何产生、如何被更新、如何被汇总」展开。所以我的习惯是拿到任何一套四方支付源码先不看业务接口先看数据库脚本里的表设计只要三张核心表的字段和状态机清楚了整个源码的架构就清楚了一半。3. 基于四方支付源码二次开发的落地路径从源码包到最小可用工程3.1 拿到源码包后的目录结构先分清聚合层与通道层假设你手头有一套典型的四方支付源码包解压后先别急着启动先看目录。常见做法是 Maven 或 Gradle 多模块工程因为聚合支付天生需要把核心模型、通道适配、后台管理、对外网关分离出来。我见过很多把它直接做成单应用的老项目一旦接入新通道核心代码被渠道 SDK 塞满最终只能推倒重来。tar -xzf pay4x-source.tar.gz cd pay4x tree -L 2 -d模拟输出pay4x ├── pay4x-common # 公共工具类、常量、统一返回模型 ├── pay4x-core # 核心业务逻辑订单服务、路由、账务 ├── pay4x-channel # 通道适配层 │ ├── pay4x-channel-wechat # 微信支付适配器 │ ├── pay4x-channel-alipay # 支付宝适配器 │ └── pay4x-channel-unionpay # 银联适配器 ├── pay4x-gateway # 对外 HTTP 网关商户接入层 ├── pay4x-admin # 运营后台商户管理、结算审核 └── pay4x-job # 定时任务日终对账、关单、结算逻辑说明pay4x-channel这一层是最重要的隔离带。每个通道适配器只允许依赖该通道的 SDK 和 pay4x-common不能依赖核心业务代码。这样新增一个通道时核心层完全不改动只是在路由配置里多注册一个实现。pay4x-job单独拎出来是对账和结算这类定时任务的正确打开方式否则在后台进程里跑调度时间一长会出现任务重复执行和内存溢出问题。3.2 配置数据库与支付渠道参数沙箱环境里的最小可跑通配置最小工程先不要接真实商户和真实密钥把沙箱参数跑通更重要。源码自带一套参考配置通常放在pay4x-core/src/main/resources/application.yml下面。我一般先改四个位置数据库连接、Redis、回调域名、通道沙箱开关。spring: datasource: url: jdbc:mysql://localhost:3306/pay4x?useSSLfalsecharacterEncodingutf8 username: pay4x password: changeit redis: host: localhost port: 6379 database: 0 pay4x: # 对外回调域名通道回调与商户通知都会拼上这个域名 notify-domain: https://api.example.com # 渠道路由默认超时时间单位毫秒 route-timeout: 3000 channels: wechat: enabled: true sandbox: true app-id: wx_demo_app_id mch-id: 10000001 api-key: ${WECHAT_API_KEY} cert-path: /data/certs/wechat/apiclient_cert.p12 alipay: enabled: true sandbox: true app-id: 2021000000000000 private-key: ${ALIPAY_PRIVATE_KEY} alipay-public-key: ${ALIPAY_PUBLIC_KEY} sign-type: RSA2 unionpay: enabled: false mer-id: unionpay_test_mer cert-path: /data/certs/unionpay/unionpay.pfx参数说明notify-domain是全站最容易配错的地方回调地址必须是对外可访问的 HTTPS 域名不能是 IP 或内网地址也不能是 1.1.1.1 这种替换占位否则通道的异步通知发不过来订单永远停在「支付中」。route-timeout是平台向上游通道发起请求的最长时间3 秒是很多团队的默认值太短容易碰到通道抖动误判失败太长会让用户在支付页等待过久。密钥部分不要直接写在 yml 里用${WECHAT_API_KEY}这类环境变量引用私钥文件路径单独放在不分发的目录这是很多源码 demo 里没做好的事。配置完成后启动顺序是先起 pay4x-job 里的基础定时任务依赖再起 pay4x-gateway。启动后先调用健康检查接口比如GET /actuator/health确认数据库和 Redis 都正常连接。然后进入管理后台创建一个测试商户拿到商户编号和签名密钥就可以开始跑一笔沙箱支付。注意沙箱环境里微信和支付宝的回调地址往往不进公网需要靠后台的模拟回调工具触发这一步等到了回调处理模块再详细说。4. 四方支付源码核心模块精读下单、回调、对账的三段关键代码4.1 下单接口策略模式是把多通道差异揉进同一段逻辑的关键四方支付源码里最常被自定义改造的就是下单接口。商户通过网关发送一个下单请求里面包含账单金额、支付方式、商户订单号平台要根据channelCode找到对应通道的适配器再返回通道要求的支付参数。直接用if (channelCode.equals(wechat))写当然能跑但每加一个通道就要改一次核心方法所以源码里更常见的做法是策略模式配合 Spring 的依赖注入。Component public class UnifiedOrderService { private final MapString, ChannelRouter routerMap; public UnifiedOrderService(ListChannelRouter routers) { // Spring 会把所有 ChannelRouter 实现注入进来key 由每个实现自己声明 this.routerMap routers.stream() .collect(Collectors.toMap(ChannelRouter::channelCode, Function.identity())); } public PayOrderResult createOrder(OrderCreateRequest request) { // 1. 基础校验商户是否存在、金额是否大于0 Merchant merchant merchantService.validAndGet(request.getMerchantCode()); if (merchant null) { throw new BizException(MERCHANT_NOT_FOUND); } // 2. 生成平台内部唯一单号格式可以带日期和随机数 String payOrderNo generatePayOrderNo(); // 3. 根据请求里的 channelCode 选择适配器未命中直接报错 ChannelRouter router routerMap.get(request.getChannelCode()); if (router null) { throw new BizException(CHANNEL_NOT_SUPPORTED); } // 4. 调用适配器下单这里只依赖统一接口 ChannelPlaceOrderResult result router.placeOrder(buildChannelRequest(request, payOrderNo)); // 5. 下单成功后保存支付流水状态为支付中 paymentOrderService.savePendingOrder(payOrderNo, request, result.getChannelTradeNo()); return PayOrderResult.success(payOrderNo, result.getPayParams()); } }逻辑说明routerMap的 key 是channelCode字符串value 是每个通道的具体实现所以新增通道时只需要增加一个实现类并注册成 Spring Bean。buildChannelRequest会把商户的原始请求转成各通道需要的格式这一步即使放在统一方法里也建议用接口隔离不要直接暴露给上层。generatePayOrderNo建议用「时间戳 商户号 随机数」而不是纯自增因为支付单号可能会出现在对账单和回调日志里纯自增容易被人推测出平台交易量。参数说明ChannelPlaceOrderResult至少要有三个字段——通道交易号、通道返回的支付参数可能是收银台 URL 或 SDK 请求参数、是否立即成功比如小额免密场景。沙箱调试时重点看router.placeOrder内部打出的请求日志通常源码里会预留log.debug(wechat place order request: {}, request)这样的输出把开关打开可以省下很多抓包时间。4.2 回调处理幂等性与签名校验两层保护缺一不可回调处理是四方支付里最容易出生产事故的代码。通道的回调通知可能因为网络抖动重复推送也可能在极端情况下延迟几小时才到。如果回调处理不是幂等的商户订单状态被二次更新金额可能重复入账这对资金安全是致命的。源码里通常会用数据库唯一索引加应用层锁来兜底。Component public class NotifyService { private final PaymentOrderMapper orderMapper; private final IdempotentLockService idempotentLock; public String handleChannelNotify(ChannelNotify notify) { // 1. 验签不通过直接返回失败让通道继续重推 boolean verified channelSignService.verifySign(notify.getChannelCode(), notify.getRawData()); if (!verified) { log.warn(notify sign invalid, channel{}, notify.getChannelCode()); return FAILURE; } // 2. 按通知 ID 做幂等存在则直接返回成功不再处理 if (!idempotentLock.tryLock(notify: notify.getNotifyId(), 10)) { return SUCCESS; } // 3. 查询内部订单确认当前状态只有支付中才更新 PaymentOrder order orderMapper.findByPayOrderNo(notify.getPayOrderNo()); if (order null || order.getStatus() ! PAYMENT_STATUS_PENDING) { return SUCCESS; } // 4. 更新订单为成功并记录通道交易号和手续费 orderMapper.markSuccess(order.getId(), notify.getChannelTradeNo(), notify.getChannelFee()); // 5. 触发对商户的异步通知通知失败则等待定时任务补偿 merchantNotifyService.push(order.getMerchantCode(), order.getOutTradeNo()); return SUCCESS; } }逻辑说明第 2 步的tryLock用的是 RedisSETNX加过期时间过期时间设置为 10 秒足够覆盖一次回调处理耗时即使处理进程宕机锁也会自动释放。第 3 步的「只有支付中才更新」是第二层幂等保护因为数据库更新本身就不是重复安全的业务上要求一次订单只能从待支付变成成功。第 5 步商户通知必须做成异步队列加失败重试渠道的回调超时时间很短如果在通知商户上卡太久通道会认为平台没有正确接收回调。参数说明notify.getChannelFee()在有些通道的沙箱环境里是空值或字符串落库前要先做空值转 0 和金额单位的统一转换。我见过的翻车案例是通道返回以元为单位的字符串内部表存的是分直接落库后整张表的对账金额全部少了 100 倍。所以回调处理里必须有一层金额单位转换用工具类统一为整数分。4.3 对账文件解析把通道侧的对账单转成平台侧可核对的差异明细日终对账是四方支付源码里最琐碎但也最能体现干脆利落的模块。通道每天生成一个原始对账单文件可能是 CSV、Excel 或类 JSON里面包含当天的交易明细、手续费、退款记录。平台要做的是把这个文件和自己库里的支付流水比对生成金额不一致或者双方单边订单的差异列表。# 以某通道的 CSV 对账单为例解析并与内部流水比对 import csv import pymysql channel_file /data/check/wechat_20250301.csv internal_orders {} conn pymysql.connect(hostlocalhost, userpay4x, passwordchangeit, databasepay4x) with conn.cursor() as cursor: cursor.execute(SELECT pay_order_no, total_amount, status FROM t_payment_order WHERE create_time %s, (2025-03-01 00:00:00,)) for row in cursor.fetchall(): internal_orders[row[0]] {amount: row[1], status: row[2]} diff_list [] with open(channel_file, r, encodingutf-8) as fp: reader csv.DictReader(fp) for row in reader: channel_trade_no row[商户单号].strip() channel_amount int(round(float(row[交易金额]) * 100)) inner internal_orders.get(channel_trade_no) if inner is None: diff_list.append({trade_no: channel_trade_no, type: 渠道单边, amount: channel_amount}) elif inner[amount] ! channel_amount: diff_list.append({trade_no: channel_trade_no, type: 金额不一致, amount_diff: channel_amount - inner[amount]}) elif inner[status] ! 1: diff_list.append({trade_no: channel_trade_no, type: 平台未成功, amount: channel_amount}) else: internal_orders.pop(channel_trade_no, None) # 内部有但渠道没有的订单属于平台单边 for trade_no, order in internal_orders.items(): if order[status] 1: diff_list.append({trade_no: trade_no, type: 平台单边, amount: order[amount]}) for diff in diff_list: print(diff)逻辑说明这段脚本先把平台内部的支付流水加载到内存字典里然后逐行读通道对账单比对。channel_amount的转换是关键对账单常见单位是元而且有小数点误差用round(float(x) * 100)转成整数分比直接用int(float(x))更稳。单边差异是指只有一方有记录需要人工核实。参数说明比对时不要用过大的时间范围建议按单日或单小时批量处理否则内存字典可能被积年数据撑爆。5. 四方支付源码二次开发避坑手册资金安全与并发场景的五个常见问题5.1 回调重复通知导致订单金额被翻倍更新现象一笔订单收到两次回调第二次回调把订单状态又从成功更新成了成功触发商户通知被推了两次商户侧库存被扣减两次。原因回调处理只判断了order ! null没有判断当前状态是不是支付中或者幂等锁的 key 用了订单号而不是通知 ID同一笔订单的多次通知共用一把锁锁过期后第二次回调继续往下走。解决把幂等锁的 key 换成notify.getNotifyId()同时在数据库更新语句里加状态条件比如UPDATE t_payment_order SET status 1 WHERE id #{id} AND status 0让数据库层拒绝重复更新。两层保护缺一不可应用层锁防并发数据库条件更新防串行。5.2 各通道签名算法不一致导致验签失败现象接入支付宝时回调验签通过接入微信时同样逻辑一直报验签失败排查发现大版本升级后 1 个通道换了新签名类型。原因不同通道的签名算法有 MD5、HMAC-SHA256、RSA2 甚至国密 SM2即使算法名称一致签名内容构造规则也完全不同。很多源码把验签逻辑直接写死在回调方法里换通道就要改核心代码。解决在通道适配器内部各自实现验签逻辑对外提供统一verifySign接口。增加通道时把该通道官方 SDK 的验签方法封装在适配器里核心业务不感知差异。遇到验签失败先打开调试日志看原始报文和参与签名的字段列表通常能排查出拼参顺序错误或字段遗漏。5.3 对账差异集中在退款订单上金额总是算不平现象日终对账脚本跑完退款订单几乎全部报「金额不一致」且差异金额恰好等于退款金额。原因对账单上退款和支付是同一行字段用交易类型区分而内部表里退款订单单独存了退款流水金额字段记录的是原始支付金额比对时拿原金额去比对退款行当然差一倍。解决先把对账单按交易类型拆分支付单比对支付流水退款单比对退款流水。退款单金额方向为负取绝对值后与内部退款表中的金额比对。同时检查平台侧是否把退款状态单独建立了t_refund_order表不要让退款流水混进支付流水表。5.4 下单接口并发压测时出现重复平台单号现象压测跑到每秒 500 个事务时数据库偶尔报唯一键冲突日志里能看到同一个payOrderNo被重复创建。原因生成单号的逻辑用了「时间戳 随机数」在高并发下时间戳粒度只有毫秒随机数随机范围有限导致碰撞概率上升单体应用里同步生成没问题部署多实例后冲突概率成倍增加。解决单号生成组件改用「雪花算法」或「号段模式」至少要保证跨进程唯一。如果源码用的是数据库自增每个实例单独每次插入会导致锁竞争建议独立一个序列表或引入 Redis 的 INCR把单号生成做成独立服务。5.5 商户回调通知失败后没有补偿机制订单支付成功但用户没收到通知现象某次通道大面积超时导致回调线程池阻塞商户回调消息积压最终消息丢失用户支付成功但商户系统没有收到同步通知只能靠用户主动查询。原因回调处理里把商户通知做成同步调用一旦商户接口响应慢线程池被占满后续通知全部排队时间一长丢弃。更糟的是没有本地消息表通知失败后没有重试入口。解决引入本地消息表回调更新订单状态后先把「待通知」记录写入t_merchant_notify_task再由独立线程扫描推送推送失败标记状态定时任务按指数退避重试。重试次数上限设 5 次超过后进人工告警。这套逻辑在做四方支付时几乎是标配没有补偿机制的生产环境早晚会出事故。6. 让四方支付源码真正可用三个进阶加固建议与验证方法第一把支付结果从依赖回调改成依赖「回调 主动查询」双向确认。通道的回调不是可靠交付会丢也会被阻塞正确的做法是在回调更新成功后再向通道发起一次主动订单查询比对两边状态。查询接口通常有频率限制所以控制在一笔订单最多主动查询两次一次在回调后 10 秒一次在回调后 5 分钟。第二给核心账务字段加防篡改校验。支付流水表里的金额、手续费、结算字段建议增加一个校验列保存这些字段的摘要值比如用 SHA-256 计算整行关键字段的结果。每天结算跑批前先做一遍完整性校验一旦发现某行数据被非法修改立刻阻断结算流程。对普通业务系统这可能是过度设计但对四方支付这种涉及真金白银的系统多一道防线好过事后追账。第三做一次全链路的渠道故障演练。选一个周末低峰期在沙箱环境模拟某通道 30 分钟完全不可用验证平台的路由切换逻辑能否自动把新订单切到备用通道存量支付中的订单能否在恢复后正常回调。演练结束后检查「支付中」状态超过 24 小时的订单确认关单任务有没有把超时订单全部关掉。这套演练的价值在于不需要等真实通道故障时才开始手忙脚乱地看日志。验证方法也很直接从商户后台发起一笔 0.01 元支付支付成功后到平台后台确认支付流水是成功状态再等到次日对账单生成后跑一遍对账脚本确认没有任何差异记录。反复跑通这个闭环说明这套源码在你的环境里是真的能用的而不是只启动成功。我的习惯是把这个验证脚本写成集成测试用例每次升级代码后先跑一遍再发版。四方支付的核心就一句话钱走哪里代码就要跟到哪里。希望这篇文章能帮你少踩一些坑愿你的账永远对得上。本文还有配套的精品资源点击获取
