ECShop 2.7.3 支付宝免签约即时到账接口接入与回调排障-育师

简介：这份支付宝免签约即时到帐接口面向使用 ECShop V2.7.3 搭建商城的站长与二次开发人员，重点解决未签约支付宝即时到账时的支付接入问题，适合需要快速补齐商城支付链路、研究免签约到账通知机制的场景。压缩包共 7 个文件，以 6 个 PHP 支付模块与 1 个 TXT 说明文档为主，整体约 7KB，体量轻便，便于部署前查看结构与按需覆盖。包内围绕接口模块、多语言支付语言包和到账通知接收逻辑组织，可帮助读者理解 ECShop 支付方式挂载、商户参数配置、异步通知处理之间的对应关系，也便于在测试环境中比对缺件、参数传递与回调路径。目前已有 318 人学习或下载，适合希望以较小成本验证免签约即时到账方案，并对现有 ECShop 支付模块做对照排查的读者参考。

1. 免签约即时到账在 ECShop 2.7.3 上到底卡在哪一步

老 ECShop 站点最尴尬的一幕：后台支付方式里明明装了支付宝，前台点“去付款”却卡在签名错误，或者付完款订单还挂着“未付款”。这份「支付宝免签约即时到帐接口 for ECShop_V2.7.3」瞄准的就是这个最窄的场景——不折腾商户签约流程，用老版即时到账 MD5 网关把ecshop的订单状态字段写入数据库，让支付宝接口在 V2.7.3 这套老框架上能直连、能回调、能对账。它适合存量站维护、内网验收环境和教学复现；如果新起项目，直接上官方开放平台签约版，别拿这份包硬撑生产。

2. 先把调用链理清：插件文件落在哪、谁调谁

拿到压缩包先别急着覆盖，ECShop 的支付插件是“约定大于配置”的结构：文件名、类名、目录位置三样必须对齐，错一个就是白屏或者支付方式列表里根本瞧不见它。

2.1 接口包的文件位置与后台配置字段

绝大多数免签约包解压出来只有三五个文件，剩下的靠 ECShop 自带的respond.php兜底。先用find把结构摊平看清楚，再决定哪些覆盖、哪些保留：

# 解压到临时目录，别直接往站点根目录扔 unzip alipay_ecshop_2.7.3.zip -d /tmp/alipay_pkg # 没有 tree 就用 find 摊平，一眼看完整个包 find /tmp/alipay_pkg -type f | sed 's#/tmp/alipay_pkg/##' # 典型输出（不同打包人略有差异）： # includes/modules/payment/alipay.php <- 插件主文件，位置写死 # languages/zh_cn/payment/alipay.php <- 后台配置项的中文标签 # includes/modules/payment/alipay_log.php <- 部分包附带的日志类，可选 # 安装说明.txt

这几个文件各管一摊，覆盖前先备份原文件，尤其includes/modules/payment/alipay.php——很多站的旧插件里存着已经调通的 partner 和 key。

包内文件	目标路径	作用	覆盖前注意
`alipay.php`	`includes/modules/payment/`	插件类本体，负责签名、下单、回调	旧文件里的配置会丢，先备份
`alipay.php`（语言包）	`languages/zh_cn/payment/`	后台“支付方式”里的名称与描述	站点是 GBK 编码要转码
`alipay_log.php`	`includes/modules/payment/`	可选，写回调日志	需要`logs/`目录可写
`安装说明.txt`	不用放	配置项取值说明	只看 partner / key 的来源

主文件放好之后，进后台“系统设置 → 支付方式 → 安装”，才会出现“支付宝（即时到账）”这一项。这一步装的东西不是文件，而是往ecs_payment表插一条记录，配置项全部序列化进pay_config字段。

配置项	典型值	说明
`partner`	2088 开头 16 位	合作身份 ID，决定钱进哪个账户
`key`	32 位字符串	MD5 密钥，签名和验签都用它，末尾空格是高频事故
`seller_email`	收款账号	回调时用来比对收款方，防止串单
`service`	`create_direct_pay_by_user`	即时到账的固定服务名，写错直接报错
`_input_charset`	`utf-8`	必须和站点编码一致，不然中文商品名乱码
`transport`	`http`/`https`	老服务器没开 openssl 时只能走 http

pay_config是序列化数组，后台每保存一次就整体重写一次。这意味着你在数据库里手改的临时参数，管理员点一下“保存”就没了——调试阶段的临时值，改完记得同步回后台表单。

2.2 一次支付从结算页到网关的完整链路

链路不长，但每一步出错的表现都不一样，先把顺序背下来，后面排查能省一半时间：

用户在flow.php确认订单，ECShop 生成order_sn并写ecs_order_info，pay_status = 0。
结算页取出当前支付方式对象，调用插件的execute()，拿到一段 HTML。
execute()内部拼参数、算签名、输出一个带隐藏域、用 JS 自动提交的表单，目标是https://mapi.alipay.com/gateway.do。
用户在支付页完成付款，浏览器被同步跳回return_url（一般是respond.php?code=alipay）。
与此同时，支付网关服务器向notify_url发 POST，同样落到respond.php?code=alipay。

关键点在第五步：respond.php干的事很固定——取code参数、加载includes/modules/payment/{code}.php、实例化类、根据type把请求分发给callback()或notify()。所以插件的文件名必须和code一模一样，类名也必须一模一样，类名写成alipay_pay而文件名是alipay.php，PHP 会在实例化那行直接报致命错误。

同步返回和异步通知走同一个入口，但语义完全不同：

通道	触发方	可信度	该干什么
`callback()`	用户浏览器跳回	低	只做展示，查一下状态给个提示
`notify()`	支付网关服务器	高	验签、比对金额、写订单状态

我见过不止一个站把发货逻辑写在callback()里，用户付款后直接关掉浏览器，订单就永远停在未付款——这不是接口的锅，是入口用错了。

2.3 插件类要补齐的方法与类骨架

ECShop 对支付插件类的约定不复杂，但__construct和同名方法都要有，因为老框架在部分代码路径上还按 PHP4 风格调用：

<?php // includes/modules/payment/alipay.php class alipay { var $code; // 支付方式代码，必须等于文件名 var $name; // 后台显示名 var $configure = array(); // 后台配置项定义 var $partner; // 合作身份 ID var $key; // MD5 密钥 var $seller_email; // 收款账号 var $gateway = 'https://mapi.alipay.com/gateway.do'; function __construct() { $this->alipay(); } // 同名方法负责初始化，从 pay_config 里把值读出来 function alipay() { $this->code = 'alipay'; $this->name = '支付宝（即时到账）'; $cfg = $GLOBALS['_CFG']['payment'] ?? array(); // 由 ECShop 注入 $this->partner = trim($this->get_cfg('partner')); $this->key = trim($this->get_cfg('key')); // 必须 trim $this->seller_email = trim($this->get_cfg('seller_email')); } function get_cfg($name) { /* 从 $this->configure 或全局配置取值 */ } function execute() { /* 返回自动提交的 HTML 表单 */ } function callback($data) { /* 同步返回，只展示 */ } function notify($data) { /* 异步通知，验签 + 改订单 */ } }

几点血泪经验：key一定要trim()，从后台复制粘贴过来的密钥尾部经常带一个空格或者换行，签名怎么算都不对，报错信息却只说“验签失败”；$this->code大小写要和文件名严格一致，Linux 服务器区分大小写，Windows 上跑得好好的搬到线上就 404；另外execute()返回的是字符串，别在里面直接echo，否则表单会跑到页面最顶上，用户看到一屏乱码。

3. 签名与参数：MD5 那 32 位到底怎么算出来的

免签约即时到账最容易被说成“玄学”的部分就是签名。其实规则只有三条：参数名排字典序、拼成k=v&k=v、末尾接密钥做 MD5。真正让人翻车的是那些规则之外的小细节。

3.1 即时到账的必填参数表

先明确哪些字段参与签名、哪些只是控制行为。参数少一个不报错，但会在支付页提示“参数不合法”；多一个不认识的字段，会被网关直接忽略，看起来一切正常但订单对不上。

参数	是否必填	示例	说明
`service`	是	`create_direct_pay_by_user`	即时到账固定值
`partner`	是	`2088xxxxxxxxxxxx`	合作身份 ID
`seller_email`	是	收款账号	必须与 partner 对应的收款方一致
`out_trade_no`	是	`20240101123456`	站内订单号，回调时靠它找单
`subject`	是	`订单 20240101123456`	商品标题，中文需转码
`total_fee`	是	`99.00`	单位元，两位小数，字符串
`body`	否	`ECShop 订单`	描述，可留空
`notify_url`	是	`https://站点/respond.php?code=alipay`	异步通知地址
`return_url`	是	同上	同步跳回地址
`payment_type`	是	`1`	1 表示商品购买
`_input_charset`	是	`utf-8`	与站点编码一致
`sign_type`	是	`MD5`	不参与签名计算

两个坑提前说：total_fee从数据库order_amount取出来直接拼进去，decimal字段可能返回99.0000，网关按字符串比较金额，多两个零就判失败；notify_url带上?code=alipay这类查询串是允许的，但连接必须公网可达、不能被防火墙拦掉 POST。

3.2 排序、拼接、MD5 的三步实现

签名函数是整个插件最不该出错的一段，写清楚注释，后面谁接手都能看懂：

<?php // $params 是待签名的参数数组，$key 是 32 位 MD5 密钥 function alipay_sign($params, $key) { // 1) 剔掉 sign / sign_type，以及值为空串的参数 unset($params['sign'], $params['sign_type']); $filtered = array(); foreach ($params as $k => $v) { // 注意：用 === '' 判断，不能用 empty()，否则 total_fee=0 会被丢掉 if ($v === '' || $v === null) { continue; } $filtered[$k] = $v; } // 2) 按参数名 ASCII 码升序排序 ksort($filtered); // 3) 拼成 k=v&k=v，值保持原始状态，不做 urlencode $pairs = array(); foreach ($filtered as $k => $v) { $pairs[] = $k . '=' . $v; } $raw = implode('&', $pairs); // 4) 末尾直接接密钥，md5 后转小写（大写网关不认） return strtolower(md5($raw . $key)); }

逐条解释一下为什么这么写。第一，sign和sign_type不参与签名是协议规定；第二，判空必须用=== ''，total_fee在某些配置下算出来是0，empty()会把它当空值剔掉，签出来的字符串和网关算的不一样，报错还看不出原因；第三，参与签名的必须是原始值，URL 编码只发生在拼表单那一步，如果先urlencode再签名，中文商品名的订单百分之百失败；第四，ksort排的是键名，不是键值，而且必须是 ASCII 序，PHP 默认的字符串比较就是 ASCII 序，一般不会错，但用了SORT_NUMERIC之类的参数就全乱了。

排查签名问题有个笨办法很有效：把签名前的$raw拼串和密钥长度一起写进日志，拿网关返回的失败信息对照，八成能看出是少参数还是编码不对。

3.3 表单自动提交与编码转换

签完名就该把用户送出站了。这一步的写法直接决定用户看到的是一个自动跳转还是一个能点的按钮：

function alipay_form($gateway, $params, $key) { $params['sign'] = alipay_sign($params, $key); $params['sign_type'] = 'MD5'; // 网关地址上的 _input_charset 必须和签名里的值一致 $action = $gateway . '?_input_charset=' . $params['_input_charset']; $html = '<form id="alipaysubmit" name="alipaysubmit" action="' . $action . '" method="POST">'; foreach ($params as $k => $v) { $html .= '<input type="hidden" name="' . $k . '" value="' . htmlspecialchars($v, ENT_QUOTES, 'UTF-8') . '" />'; } $html .= '</form>'; $html .= '<script>document.forms["alipaysubmit"].submit();</script>'; return $html; }

选择 POST 表单而不是拼一个长 URL 跳转，原因很实际：老 IE 对 URL 长度有限制，商品名带中文时 URL 编码会把长度翻三倍，超过 2000 字符直接被截断，用户点进去就是参数缺失。POST 没有这个烦恼，还能避免&被二次转义。

编码这一块按站点实际编码处理。站点是 UTF-8 就直接传；是 GBK 的话，subject和body必须先转码再参与签名，转码要在签名之前做，签完再转，签名就对不上了：

// 站点编码为 GBK 时的处理顺序：先转码，再签名 if (strtoupper($_CFG['charset']) !== 'UTF-8') { $params['subject'] = iconv('GBK', 'UTF-8', $params['subject']); $params['body'] = iconv('GBK', 'UTF-8', $params['body']); } $params['_input_charset'] = 'utf-8'; $html = alipay_form($this->gateway, $params, $this->key);

iconv遇到生僻字会返回空串，上线前用后台商品库里最长的那个标题试一次，比事后逐个订单排查省事得多。

4. 异步通知落库：notify 里该校验的四件事与幂等写法

回调是整个支付链路里唯一有“钱已经到账”这个事实的入口，写错一个字就是重复发货或者丢单。这一段值得多花半天时间写扎实。

4.1 验签之外还得比对什么

验签只证明“这个请求确实是网关发的”，不证明“这笔钱该记在这个订单上”。所以notify()里至少要过四道关：

第一道，验签。用同样的alipay_sign()对$_POST重算一遍，和请求里的sign比对，注意统一转小写再比。第二道，交易状态。只认TRADE_SUCCESS和TRADE_FINISHED两种，其它状态（比如等待付款）直接回success让网关别再推，但要写日志留痕。第三道，收款方比对。seller_email和partner必须和自己配置的一致，防止有人拿别的商户号构造请求。第四道，金额比对。把订单表里的order_amount和回调里的total_fee都当字符串比较，或者用bccomp($a, $b, 2)，直接==比浮点数，99.00和99在某些情况下会判不相等。

顺序也有讲究：验签放在最前面，不通过就直接返回失败，别急着查库；否则被刷接口的时候，数据库先挨一轮无意义的查询。

4.2 用 order_paid() 改状态，别手写 UPDATE

很多人图省事，在notify()里直接UPDATE ecs_order_info SET pay_status = 2。这么干的后果是：订单操作日志没有记录、用户积分没加、赠品没发、分成没算，后台管理员点开订单详情看到的是一片空白的时间线。

ECShop 在includes/lib_order.php里提供了order_paid($order_id)，该做的事它都做了。调用它之前把订单查出来，做完幂等判断再调用：

function notify($data) { $logfile = ROOT_PATH . 'logs/alipay_notify_' . date('Ymd') . '.log'; file_put_contents($logfile, date('c') . ' ' . json_encode($data) . "\n", FILE_APPEND); // 1) 验签 if (empty($data['sign']) || alipay_sign($data, $this->key) !== strtolower($data['sign'])) { file_put_contents($logfile, "sign_fail\n", FILE_APPEND); exit('fail'); } // 2) 交易状态，非成功状态直接回 success，避免网关反复重推 if (!in_array($data['trade_status'], array('TRADE_SUCCESS', 'TRADE_FINISHED'))) { exit('success'); } // 3) 收款方比对 if ($data['seller_email'] != $this->seller_email || $data['partner'] != $this->partner) { file_put_contents($logfile, "seller_mismatch\n", FILE_APPEND); exit('fail'); } // 4) 查订单，order_sn 必须转义后再拼 SQL $order_sn = addslashes(trim($data['out_trade_no'])); $sql = "SELECT order_id, order_sn, order_amount, pay_status FROM " . $GLOBALS['ecs']->table('order_info') . " WHERE order_sn = '$order_sn' LIMIT 1"; $order = $GLOBALS['db']->getRow($sql); if (empty($order)) { file_put_contents($logfile, "order_not_found: $order_sn\n", FILE_APPEND); exit('fail'); } // 5) 幂等：已付款的订单直接回 success，不再走后续流程 if ($order['pay_status'] == PS_PAYED) { exit('success'); } // 6) 金额比对，用 bccomp 保留两位小数 if (bccomp($order['order_amount'], $data['total_fee'], 2) !== 0) { file_put_contents($logfile, "amount_mismatch: {$order['order_amount']} vs {$data['total_fee']}\n", FILE_APPEND); exit('fail'); } // 7) 走 ECShop 官方流程，订单日志、积分、赠品都会连带处理 order_paid($order['order_id']); exit('success'); }

参数说明几个容易忽略的点：PS_PAYED是 ECShop 定义的常量，值为 2，别硬编码数字；$GLOBALS['ecs']->table()会自动加表前缀，直接写ecs_order_info在改过前缀的站上必然报错；$GLOBALS['db']->getRow()是 ECShop 自带的查询封装，返回关联数组，取不到返回空数组，用empty()判断即可。

4.3 日志、超时与重复推送

网关的推送策略是“没收到 success 就一直重推”，间隔从几分钟到几小时不等，总共会推若干次。这既是保障也是陷阱：如果不做幂等，用户会被发好几次货；如果notify()处理时间太长（比如里面同步调了短信接口），网关会判超时，继续重推。

我的做法是：notify()里只做验签、改状态、写日志三件事，凡是耗时的动作（发短信、推 ERP、生成电子面单）全部踢到队列或者另外的定时脚本里。日志按天切分，文件名带日期，出问题时能按订单号grep出完整的推送轨迹，比翻服务器访问日志快得多。

还有一点：exit('success')输出的字符串必须是纯success，前面不能有任何空白、BOM 或者 PHP 报错信息。文件保存成 UTF-8 带 BOM 是重灾区，PHP 把 BOM 当正文输出，网关收到的就是\xEF\xBB\xBFsuccess，判定为失败，于是无限重推。

5. 常见问题排查：五类翻车现场的现象、原因与解法

下面这五条基本覆盖了免签约接口在 ECShop 2.7.3 上九成以上的故障，按出现频率排序。

5.1 一直提示验签失败，参数怎么看都没问题

现象：跳转到支付页立刻返回“签名验证失败”或者“invalid sign”，日志里连订单号都没有。

原因：九成是密钥带的隐形字符。从后台复制key时尾部跟了一个空格、一个换行，或者从网页复制时把全角空格带进来了；剩下的一成是签名前的参数集合和网关收到的不一致，比如某个参数值是null被implode拼成了空串，或者用了http_build_query导致值被 URL 编码后才参与签名。

解决：先var_dump(strlen($this->key))看一眼长度是不是 32，不是就trim()加preg_replace('/[\x00-\x1F\x7F]/u', '', $key)洗一遍；再把签名前的$raw拼串完整打进日志，逐字符和网关文档里的示例对照。有个快速自查法：拿两个参数手算一遍 MD5，和代码输出比对，能立刻定位是排序问题还是拼接问题。

5.2 用户付了钱，订单还是“未付款”

现象：支付页显示成功，回到站内也提示支付成功，但后台订单状态纹丝不动。

原因：callback()里写了“支付成功”的提示，但notify()因为验签失败、订单号找不到或者金额对不上而exit('fail')，网关重推几次后放弃。也可能是notify_url填的是内网地址或者带端口的测试域名，公网根本访问不到。

解决：先看logs/alipay_notify_YYYYMMDD.log有没有记录。一条都没有，说明请求没到服务器，检查notify_url是否公网可达、是否有防火墙拦 POST、respond.php是否被别的插件覆盖。有记录但都是sign_fail或amount_mismatch，问题就在插件逻辑里，按上一节逐条对。

5.3 同一笔订单发了好几次货

现象：用户投诉收到多份发货通知，后台订单操作日志里order_paid出现了好几次。

原因：没有做幂等判断。网关在没收到success时会重推，而每次重推都完整走了一遍“改状态 + 加积分 + 发赠品”的流程。

解决：在notify()开头查订单的pay_status，等于PS_PAYED就直接exit('success')。这个判断要放在金额比对之前、验签之后，既避免重复处理，又不给伪造请求可乘之机。另外order_paid()内部对已付款订单也有一定保护，但别指望它，自己加一层更稳。

5.4 商品名带中文就报参数错误

现象：英文商品名的订单能正常支付，中文商品名一律失败。

原因：站点是 GBK 编码，直接把 GBK 的中文塞进参数表并参与签名，而_input_charset写的是utf-8，两边算出来的字符串字节不同，签名自然对不上。

解决：在签名之前把subject和body用iconv('GBK', 'UTF-8', $str)转一遍，_input_charset固定utf-8；如果站点本身是 UTF-8 就不用转，但要把_input_charset和站点编码对齐，别一边 utf-8 一边 gbk 混着来。

5.5 后台改完支付配置，前台突然不能付了

现象：管理员在后台调整了支付方式的排序或者描述，保存之后前台支付按钮消失，或者跳转时报参数缺失。

原因：pay_config是序列化字段，后台每次保存都会整体重写。如果之前为了调试在数据库里手工塞过参数，保存一次就被清空；另外某些版本的 ECShop 在保存支付方式时会重建payment表记录，code字段大小写被改写，和文件名对不上。

解决：所有配置项老老实实在后台表单里填，别直接改库；改完支付方式后去includes/modules/payment/确认文件名没被改动；测试环境先跑一遍下单流程再放到生产。养成习惯：任何涉及pay_config的调整，改完先拿一笔一分钱的测试订单走通全链路。

6. 上线前的联调自检：把回调重放三遍再放手

真正让这套接口稳下来的不是代码写得多漂亮，而是上线前那半小时的“折腾”。我一般会在测试环境做三件事：先用真实参数重放一次notify，验证验签和幂等；再把同一份 POST 重放三遍，确认第二、三次都直接返回success且订单没有任何变化；最后手动把total_fee改掉一位小数重放，确认金额校验真的能拦住。

重放用curl最省事，把日志里抓到的真实参数原样贴进去：

# 用日志里的真实参数重放一次异步通知，注意 URL 里要带 code=alipay curl -i -X POST 'https://shop.example.com/respond.php?code=alipay' \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data 'partner=2088xxxxxxxxxxxx&seller_email=pay%40example.com&out_trade_no=20240101123456&total_fee=99.00&trade_status=TRADE_SUCCESS&sign=算出来的签名&sign_type=MD5' # 期望返回：HTTP 200，响应体只有 success 四个字母 # 如果返回整页 HTML，说明 respond.php 之前有输出，检查文件 BOM 和 PHP 短标签

上线自检清单我固定跑这几项：

检查项	判定标准	不通过的表现
插件文件名与类名	完全一致且大小写匹配	前台支付方式列表空白
`key`长度	严格 32 位，无空白字符	验签必失败
`notify_url`可达性	公网 POST 能返回`success`	订单永远未付款
幂等	同一笔重放三次状态不变	重复发货
金额比对	改一分钱能被拦住	少付也能通过
日志目录权限	`logs/`可写	出问题无从查起

那次教训挺深的：一个站的notify()里忘了exit，respond.php后面又跟着模板输出，返回给网关的是整页 HTML，网关判定失败开始无限重推，一晚上同一笔订单被处理了十几次。从那以后我每接一个支付插件，都强制把notify手动重放三遍、改一次金额、看一眼日志，三关全过才敢放到线上。这份包的价值不在于它有多新，而在于它把这些老框架上的边界都趟过一遍，照着上面的顺序走，大部分坑都能提前避开。希望帮到你。

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