简介：码支付mpay是一款面向个人开发者与小微商家的开源免签收款工具，仅凭普通收款码即可实现支付通知自动回调，兼容绝大多数商城系统。项目基于易支付接口标准开发，支持微信、支付宝个人账户免签约收款，主打聚合码收款、免挂机不掉线、多平台多账号多通道轮询，H5环境中同样支持长按识别扫码支付。压缩包共937个文件、34.4MB，以PHP业务逻辑、JavaScript交互、CSS样式及PNG图片为主；51个PHP文件对应接口回调与轮询控制，83个CSS搭配500余张图片搭建出基于layui的完整管理后台，同时包含移动端适配样式、字体图标及部署配置样例。开源免费且持续更新，资源上线后已有164人学习下载。从源码中可以学习免签支付回调验签流程、易支付接口对接方法、订单通知处理机制和多通道轮询切换策略；目录结构完整、注释清晰，适合有PHP基础的开发者直接二次部署，也可作为支付系统开发的实战案例。
1. 码支付mpay到底解决了什么问题：个人免签收款与自动回调的完整链路
在做个人开发者的这几年，我接过的最扎手的活不是业务逻辑复杂，而是收款——没有企业资质接不了官方支付接口，用别人的聚合码又拿不到订单回调，每笔到账都得靠人工盯，订单状态全靠手动改。码支付mpay这套工具解决的问题正好卡在这个点上：把你手里的普通收款码变成能自动回调的业务接口，商户下单、扫码付款、异步通知、订单状态流转，一条链路串完，绝大多数商城系统都能直接对接。这篇文章不是来介绍功能的，是把我拆过的码支付mpay源码、调试过的回调流程、以及踩过的坑原样摆出来，后面你照着改就能用。适合有三方商城开发经验、正准备把个人支付体系跑起来的从业者。需要先说清楚一点，个人收款码用于经营性收款在不同地区有不同合规要求，本文只讨论技术对接层面，实际落地前请先自己确认政策边界。
很多第一次接触码支付的人会把“免签收款”想复杂，觉得这是某种黑客技术。其实它只是一套支付托管方案：商城系统按协议发起一笔交易，码支付返回一个收款二维码，用户扫码完成付款后，平台通过异步回调告诉你结果。难点从来不在生成二维码，而在“回调是否可靠”这件事上。
2. 从收款码到回调通知：链路设计与签名规则
2.1 免签收款不是黑匣子，核心是把“到账事件”变成HTTP回调
码支付的完整链路通常是这样的：商城系统生成订单，跳转到支付收银台，用户用微信或支付宝扫码，钱到了收款码对应的账户，然后码支付平台向商城系统配置的异步通知地址发起一次HTTP POST，携带订单号和金额，商城系统处理完业务逻辑后返回一个同意接收的响应，这笔订单才算闭环。
链路里最关键的“异步通知”，其实就是开发者天天挂在嘴边的回调函数概念在支付场景里的具体落地。回调函数的核心特征是“在某个事件发生时，把一段逻辑从外部注入并执行”。你看JavaScript里的写法，一个js回调函数实例就是先定义一个函数，再把它作为参数传给另一个方法，等异步操作完成时触发。python回调函数也一样的套路，把处理函数作为参数传入，事件发生后被调用。码支付的notify_url就是商城系统向支付平台“注册”的那个回调入口，支付平台确认收款后在服务端发起HTTP请求，调用的就是你那个回调地址背后的处理逻辑。这个理解一旦建立，后面的验签、幂等、异常处理就都有了框架。
这里有一个非常常见的误解：有人以为同步跳转地址return_url返回了、页面显示付款成功，就能去更新订单状态。不行，同步跳转是浏览器行为，用户可以伪造页面、也可以中途关闭，它只适合做前端展示。凡是在浏览器环境里能伪造的都不能作为业务凭证，后续统一以后端异步通知为准。这个规则在国内支付体系里几乎是通用的，你看支付宝回调、微信支付回调，也都是把异步通知当作真正的订单凭证，没有一个是靠前端跳转来记账的。
如果你不想依赖服务端异步通知，也有别的做法：写一个定时脚本，每隔一段时间去查询码支付平台的订单状态，查到已支付就同步更新本地订单。本质上就是自己实现了一套轮询回调。这个方案适合站点环境特殊、对外服务端口受限的情况，但口子不如异步通知即时，实时性差几秒到几分钟。
2.2 回调参数与签名规则：先看懂再动手
对接码支付之前，最该先研究的是它的回调参数和签名规则，因为这直接决定了后端验签代码怎么写。码支付作为易支付协议系的一种实现，回调参数大体是固定的。我把常用参数列成了一张表，对接时直接对着抄：
| 参数名 | 含义 | 说明 |
|---|---|---|
| pid | 商户ID | 在码支付后台开通后生成，类似你在平台的身份标识 |
| out_trade_no | 商户订单号 | 由商城系统生成，回调时平台原样返回 |
| trade_no | 平台交易号 | 码支付平台自己的流水号，用于对账 |
| type | 支付方式 | alipay表示支付宝，wxpay表示微信，qpay表示QQ钱包 |
| money | 订单金额 | 字符串类型，比如“0.01”，不要用浮点数比较 |
| name | 商品名称 | 下单时传入的商品描述 |
| sign | 签名值 | 验签时核心比对对象 |
| sign_type | 签名类型 | 码支付统一用MD5 |
签名规则在易支付协议里比较统一：除了sign和sign_type之外，把其他所有参数按参数名ASCII码升序排列，用URL键值对格式拼接，然后在末尾拼接商户密钥，对拼接结果做MD5得到签名值。PHP里构造签名可以这样写：
<?php // 生成支付请求签名 function buildSign(array $params, string $key): string { // 1. 过滤签名参数和空值 unset($params['sign'], $params['sign_type']); $params = array_filter($params, function ($value) { return $value !== '' && $value !== null; }); // 2. 按参数名ASCII升序排序 ksort($params, SORT_STRING); // 3. 拼接成 a=b&c=d 形式 $signStr = urldecode(http_build_query($params)); // 4. 末尾拼接商户密钥 $signStr .= $key; // 5. MD5 并转小写 return md5($signStr); }逻辑上，这个函数做的是“待签名串构造”这件事。很多新手会漏掉第1步的参数过滤，导致平台签名和本地签名永远对不上。实际对接中，平台回调时参数里可能混入空字段，你不过滤，拼接出来的待签名字串就多出一个空值，签名结果自然不一致。第3步用urldecode包裹http_build_query，是为了确保中文参数和特殊字符在做URL编码后还能还原成平台拼接时的原始样子。如果这里不处理，商品名里带中文或带“&”时，验签十有八九会失败。
3. 把码支付mpay接进商城系统：PHP对接与模块改造实录
3.1 准备阶段：回调地址、密钥与接口域名
对接前要把四样东西准备好，缺一个后面都会卡住：商户ID、商户密钥、异步回调地址、同步跳转地址。商户ID和密钥在码支付后台的商户信息页里能看到，商户密钥只展示一次，复制之后要立刻存到本地配置里，别等上线了再回去找。异步回调地址是一个外网可访问的POST接口地址，比如https://yourdomain.com/notify.php，这个地址必须保证公网能访问到，不能用localhost，也不能用内网IP。
同步跳转地址是用户支付完成后浏览器跳回的页面，通常写https://yourdomain.com/order/detail.html?id=xxx。这里有一个大家特别容易搞混的点：项目中如果同时涉及微信网页授权，“网页授权回调域名”和码支付的异步回调地址是两个完全不同的东西。网页授权回调域名是配置在微信公众平台后台、限制前端跳转使用的；而码支付的notify_url是一个服务端接口入口，不需要配置到微信后台，两者不要互相替换。
另外，对接前还要确认商城系统里有没有“易支付”这类通用支付插件。码支付兼容的是易支付接口协议，绝大多数商城系统，包括ThinkPHP系的商城、ECShop二次开发项目、还有各类开源商城，都预留了易支付或码支付的支付接口。有的系统后台甚至直接有“码支付”配置项，只需要把支付网关地址替换成码支付平台的网关地址，再把商户ID和密钥填进去就行。
3.2 发起支付请求：生成订单并跳转收银台
商城系统在用户提交订单后要做两件事：先在本地生成一条待支付的订单记录，再向码支付收银台发起支付请求。发起支付请求的PHP代码可以封装成一个类：
<?php // 发起码支付请求，返回支付URL class MpayClient { private string $pid; private string $key; private string $gateway = 'https://pay.yourmpay.com/submit.php'; public function __construct(string $pid, string $key) { $this->pid = $pid; $this->key = $key; } public function getPayUrl(string $orderNo, string $money, string $name, string $notifyUrl, string $returnUrl, string $type = 'alipay'): string { $params = [ 'pid' => $this->pid, 'type' => $type, 'out_trade_no' => $orderNo, 'notify_url' => $notifyUrl, 'return_url' => $returnUrl, 'name' => $name, 'money' => $money, 'sign_type' => 'MD5', ]; $params['sign'] = $this->buildSign($params, $this->key); return $this->gateway . '?' . http_build_query($params); } }这里把签名构造逻辑复用了上一章的函数，对外只暴露了getPayUrl一个方法。参数里type默认给了alipay，实际场景里让用户在收银台选择微信或支付宝，再把对应值传进来。out_trade_no必须保证在商城系统里唯一，通常直接用订单号，不要拿时间戳当订单号，否则回调回来无法定位是哪笔订单。notify_url和return_url要传完整公网地址，不能写相对路径。
拿到这个支付URL之后，常见的处理方式是重定向。PHP里用header('Location: ' . $url);即可，也可以用模板表单方式提交。有的商城系统需要在收银台页面显示二维码，那就把URL转成QRCode图片，用户扫码后自动跳到收银台完成支付。这个过程本身不复杂，真正容易翻车的是异步回调的接收端写得不严谨。
3.3 接收异步通知：一段可直接放用的回调逻辑
异步回调是整条链路里最核心的入口。码支付平台确认收款后，会向notify_url发起POST请求，请求参数里包含订单号和金额。这里我给出一段可以直接放进项目的PHP回调处理代码：
<?php // notify.php - 码支付异步回调入口 $pid = $_POST['pid'] ?? ''; $orderNo = $_POST['out_trade_no'] ?? ''; $tradeNo = $_POST['trade_no'] ?? ''; $type = $_POST['type'] ?? ''; $money = $_POST['money'] ?? ''; $name = $_POST['name'] ?? ''; $sign = $_POST['sign'] ?? ''; // 1. 取本地商户密钥 $localPid = '10001'; $key = 'abcdef1234567890'; // 2. 校验商户ID，防串单 if ($pid !== $localPid) { file_put_contents('notify_error.log', 'pid mismatch: ' . $pid . PHP_EOL, FILE_APPEND); exit('fail'); } // 3. 重新计算签名并比对 $params = $_POST; $signStr = buildSign($params, $key); if (!hash_equals($signStr, $sign)) { file_put_contents('notify_error.log', 'sign error: ' . json_encode($_POST) . PHP_EOL, FILE_APPEND); exit('fail'); } // 4. 幂等检查：订单是否已经是已支付状态 $order = getOrderByOrderNo($orderNo); if (!$order) { exit('fail'); } if ($order['status'] === 'paid') { echo 'success'; exit; } // 5. 金额比对：用字符串比较，避免浮点误差 if ($order['total_amount'] !== $money) { file_put_contents('notify_error.log', 'amount mismatch: ' . $orderNo . ' expect ' . $order['total_amount'] . ' got ' . $money . PHP_EOL, FILE_APPEND); exit('fail'); } // 6. 更新订单状态，写支付流水 updateOrderPaid($orderNo, $tradeNo, $type); // 7. 返回 success，让平台停止重试 echo 'success';这段代码里每步都有意图。第2步校验商户ID，防止其他商户的回调打到你的接口上；第3步用hash_equals做签名比对，它比===更安全，也能避免字符串比较的时间侧信道问题；第4步的幂等检查很关键，平台可能因为网络问题多次推送同一个回调，不判断直接更新，会把订单状态反复覆盖；第5步金额必须用字符串比较，浮点数0.1加0.2得到0.30000000000000004，一旦参与比较就会出现对不上账的情况；第6步更新订单状态时，最好把trade_no一并存进流水表，后续对账会用到；最后必须输出success文本，否则码支付平台会认为回调失败，进入自动重试流程，重试次数多了还会触发人工审核，订单就会被长时间挂着。
4. 验签与幂等处理：把回调地址变成可靠的数据入口
4.1 签名校验实操：别让伪造通知混进订单系统
上一章的回调代码里，第3步验签写成了一行函数调用，实际生产环境里这一步值得展开讲讲。码支付的验签规则是：取回调收到的全部参数，排除sign和sign_type，剩下的参数按参数名升序排列，拼接成URL键值对字符串，末尾附上商户密钥，计算MD5，与回调里的sign比对。注意，参与签名的是回调原始参数，不是你自己重新组装的那几个参数。有些开发者图省事只拿几个关键参数拼串，结果平台多传一个参数，签名就永远对不上。
<?php // 通用易支付验签：直接用$_POST参与计算 function verifyMpaySign(array $post, string $key): bool { if (empty($post['sign'])) { return false; } $params = $post; unset($params['sign'], $params['sign_type']); ksort($params, SORT_STRING); $signStr = urldecode(http_build_query($params)) . $key; return hash_equals(md5($signStr), $post['sign']); }这个函数建议放到公共工具类里，商城系统里多个支付入口都能复用。实际使用时，不要拿第2章的buildSign函数去验签，因为buildSign会过滤空值，而验签时应该保留原始参数结构，更稳妥的做法就是单独写一个verifyMpaySign。前者是发起端用本地已知参数构造签名，后者是接收端用平台回传的原始参数还原签名，场景不同，处理细节也不同。
这里也顺带提一句前端依赖问题。很多商城前端在return_url页面上放了一个js回调函数实例，用来展示“支付成功”的弹窗。这个可以做，但只能做展示，绝不能把js回调里的订单状态当作更新业务数据的依据。原因很直白，前端地址栏可以改，页面可以被伪造，js回调函数是运行在用户浏览器里的，根本没法保证可信。以前接过一个项目就是吃了这个亏，同步页面拿到订单号后直接更新数据库，结果被人写脚本疯狂刷单。从那以后我给自己定了一条规矩：前端一切展示都只是展示，数据变更只认服务端异步回调。
4.2 重复回调与掉单：幂等表、状态机和对账机制
回调接口设计里第二个大问题是“重复回调”。网络请求不像本地函数调用，失败会自动重试，支付平台的重试策略通常是在回调得到非success响应后，隔几秒、几分钟反复推送，有的平台会持续重试24小时。如果回调处理逻辑没有幂等保障，同一个订单被处理两次，轻则重复发短信，重则把已发货订单又标记成待发货，酿成资损级别的线上事故。
幂等处理最简单有效的做法是：在订单表上加一个唯一索引约束，状态流转时用条件更新。比如更新订单状态的SQL写成这样：
UPDATE orders SET status = 'paid', trade_no = '?' WHERE order_no = '?' AND status = 'pending'这条SQL只更新状态还是pending的订单，如果订单已经变成paid，影响行数为0，自然不会被覆盖。再配合一个支付流水表，把每次回调的trade_no和order_no记录进去，流水表同样对out_trade_no建唯一索引。这样即使平台重试十次，数据库层面也只写入一条流水。
掉单是另一个方向的问题，表现为用户付了钱但商城系统没有更新订单。光靠回调本身兜不住所有场景，所以还要有对账机制。常见做法是写一个定时任务，每天凌晨从码支付平台拉取前一日的订单列表，和本地订单表做一次比对，凡是本地状态未支付但平台已支付的订单，自动补齐状态更新。这个对账脚本哪怕写得粗糙一点都值得跑起来，它能兜住很多极端场景。
5. 码支付mpay对接避坑清单：五个高发翻车现场
5.1 上线后30秒没回调，订单一直卡在待支付
现象是用户明明付了款，商城后台订单状态还是待支付，等了半小时也不动。 原因大概率是异步回调地址不对或不可达：有人把notify_url填了localhost，有人填了内网地址，还有人是服务器防火墙挡掉了POST请求，码支付平台根本连不上你的回调接口。 解决方法是先拿curl在服务器上模拟一次码支付平台的请求，确认接口能通：curl -x POST -d "pid=1&out_trade_no=TEST&money=0.01" https://yourdomain.com/notify.php。然后在notify.php入口加一行日志，打印全部POST参数，再让平台重推一次，看日志是否进来。
5.2 金额精度对不上，回调是0.1，商城记了0.01
现象是订单金额是1元，回调日志里显示0.1，数据库里存成了0.01，账目完全对不上。 原因是浮点数精度丢失。PHP里0.1 + 0.2的结果是0.30000000000000004，任何浮点运算都会引入误差，直接把浮点结果入库自然出错。 解决方法是金额在整个链路里都按字符串或整数分来处理。数据库字段用decimal(10,2)，PHP比较用字符串比较，比如$order['total_amount'] === $money。下单时也要对金额做格式化，统一保留两位小数，不要靠PHP自动转换。
5.3 本地联调跑通，上线就掉单
现象是本地环境里支付流程完整跑通，一部署到云服务器就各种收不到回调。 原因是本地环境通常用https://localhost/notify.php或者内网穿透地址测试，码支付平台能访问到；正式环境里如果域名没备案、服务器没开443端口、或者回调地址写成了IP，都会被卡住。 解决方法是在正式环境部署前，先去码支付后台确认回调地址是完整的公网HTTPS地址，再确认服务器安全组放通了80和443端口。我一般会在回调接口里加一行请求来源日志，上线后先下一笔0.01元的测试单，确认日志里出现码支付平台的请求来源IP，才算真正联通。
5.4 ThinkPHP等框架下回调地址被路由规则截断
现象是用码支付回调时接口一直返回404，但直接在浏览器打开notify.php又能访问。 原因是框架的路由规则把带参数的POST路径重写了，或者伪静态规则把notify.php吞掉了，码支付平台发出的POST参数没有被框架正确解析。 解决方法是ThinkPHP里在路由配置中给回调地址加一条例外规则，或者用物理路径访问，比如https://yourdomain.com/index.php/notify。如果项目里开了强制路由或路径别名，排查优先级放到第一位。这个坑的特点是本地环境不一定会重现，因为本地开发服务器没有走Apache或Nginx的伪静态规则。
5.5 重复回调导致订单状态被反复覆盖
现象是订单状态在已支付和待发货之间来回跳动，用户收到多条支付成功短信。 原因是码支付平台的重试机制叠加用户手动刷新页面，同一个订单触发了多次回调处理。 解决方法是给订单表加唯一索引和条件更新，前面第4章已经写过SQL写法。这里再补一个习惯：回调处理里凡是涉及状态变更的，统一用状态机守卫，只允许从待支付流转到已支付，不允许已支付回滚。在流水表里记录每次回调的完整参数，方便事后排查是由哪个环节触发的重复更新。
6. 高可用进阶：把回调流程做成半夜不用爬起来的样子
6.1 三层兜底：重试队列、延迟对账与人工补偿
异步回调再可靠也架不住极端情况，平台方服务抖动、回调HTTP超时、业务代码临时报错，任何一个环节出问题都会变成凌晨两点的一通电话。我的做法是给回调流程做三层兜底：第一层是码支付平台自带的自动重试，回调接口没有返回success时平台会按照自己的策略重试多次，这一层基本能覆盖简单故障；第二层是自己加一个延迟对账脚本，每半小时扫描一次本地订单表里超过10分钟仍未完成的订单，主动去码支付平台查询状态，查到了已支付就补齐更新；第三层是人工补偿入口，后台提供一个“按订单号重新查询”的按钮，运营人员发现异常可以主动触发查询。
第二层的延迟对账脚本可以用PHP任务调度器实现，核心逻辑很简单：查订单表、调平台查询接口、比对状态、更新订单。脚本跑起来之后，大多数回调丢失问题在半小时内就能被自动修复，不用等人工发现。
6.2 人人都该有的回调验收清单
上线前把下面这张清单走一遍，能挡掉绝大多数低级事故：
| 检查项 | 验证方法 | 预期结果 |
|---|---|---|
| 回调地址公网可达 | 用curl POST测试notify.php | 返回success |
| 签名校验通过 | 下一笔0.01元测试单 | 日志记录验签成功 |
| 重复回调幂等 | 手动重推同一笔回调两次 | 订单状态只改变一次 |
| 金额精度正确 | 用1.10元测试订单 | 数据库存1.10，回调比对一致 |
| 掉单自动修复 | 删掉一条已支付订单再跑对账脚本 | 订单被自动补为已支付 |
我自己每次上线新项目的支付模块都强制走一遍这个清单，不跳过任何一项。前几年吃过亏，觉得验签麻烦直接关了，结果线上被人伪造回调狂刷积分，后台修复数据修到凌晨。从那以后我给自己立了条规矩：支付模块宁可多花一小时做防守，也不愿半夜被电话吵醒，这些坑踩过一次就够了。希望这些实战记录对你也有用。
本文还有配套的精品资源，点击获取
