企业官网建设流程全解析

如果你最近在搞微擎小程序商城，估计已经碰到过这种情况：前端订单列表、购物车都跑通了，结果一到支付环节就卡住，后端统一下单报一个“签名错误”或者“appid与mch_id不匹配”，群里报错截图一张接一张。微信支付的后端链路比前端要敏感得多，密钥、签名、回调都在服务端完成，很多新手第一次接的时候，连prepay_id都没拿到就被拦在门外。这篇文章不聊小程序端的按钮样式和wx.requestPayment封装，专门讲微擎模块里微信支付的后端实现：从统一下单、签名、回调验签、订单状态更新，再到退款和常见故障排查。无论你是第一次接支付，还是已经被回调折磨了一整天，都可以对照着排查。

1. 支付功能整体设计思路

1.1 为什么支付逻辑必须放在后端

先明确一个原则：小程序端永远不要保存商户密钥，也不要去组装支付签名。微信支付的设计思路是“后端统一下单、前端拉起支付”，真正和微信支付后台打交道的是你的服务器，而不是小程序。小程序里能做的只有通过微信登录拿到openid，然后把订单号传给后端，拿到后端返回的支付参数，再调用wx.requestPayment。

这样做有三个原因。第一是安全，签名密钥、商户号这些信息高度敏感，如果打包进小程序代码，很容易被反编译拿到。第二是业务闭环，支付结果必须和订单状态同步，你得在服务端记录用户买了什么、付了多少钱、订单当前是什么状态。第三是很多业务逻辑必须后端执行，比如库存扣减、优惠核销、积分变动，这些不能依赖前端告诉你的结果，否则用户可以伪造。

如果你之前做过公众号支付，注意不要把两套配置搞混。公众号支付和小程序支付虽然都叫 JSAPI 下单，但appid和openid的体系完全不同：公众号支付用的是公众号的 AppID 和公众号用户的 openid，小程序支付必须用小程序的 AppID，并且openid要通过小程序的wx.login拿到 code 后换出来。用公众号配置跑小程序商城，统一下单基本都会报参数错误或商户号不匹配。

1.2 微擎模块中支付代码的文件规划

在微擎开发里，模块通常有manifest.xml、site.php、module.php以及各种自定义类。很多开发者喜欢把支付逻辑直接堆在module.php里，结果一个方法几百行，后续改需求非常痛苦。我的习惯是在模块目录下单独建一个class/子目录，把支付相关操作封装成一个PayService类，统一下单、验证回调、发起退款、关闭订单全部作为类方法管理。

大致结构如下：

addons/你的模块名/ ├── manifest.xml ├── site.php ├── module.php └── class/ └── PayService.php

module.php里只保留小程序 API 入口，比如doPagePay、doPageNotify，真正的支付逻辑丢给PayService去处理。这样做的好处是，等后面要接多个支付渠道，或者需要做退款售后，你只需要在PayService里扩展，不会污染主入口。微擎的模块加载机制本身就支持require或自动加载类文件，把类放到class/目录后，在入口处引入一次，后面就能到处复用。

1.3 一次支付请求的完整流转

一次完整的小程序支付，从用户点击“立即支付”到最后拿到订单结果，后端要参与多个环节：

1. 小程序端把订单 ID 传给后端支付接口。

2. 后端查出订单，校验订单归属、商品状态、应付金额。

3. 后端组装参数，调用微信统一下单接口，携带openid、订单号、金额、回调地址等。

4. 微信返回prepay_id，后端基于该值构造小程序端签名参数，包括timeStamp、nonceStr、package、paySign。

5. 小程序拿到参数后调用wx.requestPayment。

6. 用户输入密码，微信扣款成功后异步通知后端notify_url。

7. 后端验签并更新订单状态，返回SUCCESS。

8. 小程序端通过wx.requestPayment的 success 回调，再次查询订单状态并刷新页面。

这个流程里，第 6 步最容易被忽视。很多开发者只处理前端回调，导致支付成功但订单还是待支付。实际上微信能不能确认支付成功，以后端收到异步通知为准，前端回调只是用户体验视角，不能作为数据库订单状态的最终依据。这也是为什么本文花大量篇幅讲回调实现。

2. 微信支付后端核心要点

2.1 配置管理与密钥读取

微擎模块的配置通常通过模块后台设置保存，代码里用$this->module['config']读取。你需要在模块设置里录入小程序 AppID、商户号mch_id、API 密钥、证书文件路径等。不要把这些配置写死在代码里，否则换环境要改代码，一旦代码被分享，密钥也会泄露。

常用配置项整理如下：

读取配置的典型写法：

$config = $this->module['config']; $appId = $config['appid']; $mchId = $config['mch_id']; $apiKey = $config['api_key'];

注意 API 密钥不是小程序 AppSecret。api_key需要登录微信商户平台自行设置，它用于给请求参数签名；AppSecret 是换取openid用的，这两者不要混。日志里也不要输出api_key，否则排障时一旦日志泄露，密钥相当于直接暴露。

2.2 统一下单接口实现

统一下单是后端支付的核心请求，微信支付 APIv2 的请求地址是https://api.mch.weixin.qq.com/pay/unifiedorder，请求和响应都是 XML。为了代码整洁，我一般把三个基础函数先写出来：数组转 XML、XML 转数组、生成随机字符串。

随机字符串生成方法：

private function createNonceStr($length = 16) { $chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'; $str = ''; for ($i = 0; $i < $length; $i++) { $str .= $chars[mt_rand(0, strlen($chars) - 1)]; } return $str; }

然后是签名函数。微信支付要求把所有参数按名称做 ASCII 字典序排序，拼接成key=value的请求原串，再在末尾拼上key=你的API密钥，最后做 MD5 并转大写：

private function buildSign($params, $apiKey) { // 过滤空值和签名本身 foreach ($params as $key => $value) { if ($key == 'sign' || $value === '') { unset($params[$key]); } } ksort($params); $stringA = ''; foreach ($params as $key => $value) { $stringA .= $key . '=' . $value . '&'; } $stringA .= 'key=' . $apiKey; return strtoupper(md5($stringA)); }

统一下单方法：

public function unifiedorder($openid, $orderNo, $totalFee, $body) { $url = 'https://api.mch.weixin.qq.com/pay/unifiedorder'; $params = [ 'appid' => $this->config['appid'], 'mch_id' => $this->config['mch_id'], 'nonce_str' => $this->createNonceStr(), 'body' => $body, 'out_trade_no' => $orderNo, 'total_fee' => intval($totalFee), 'spbill_create_ip' => $this->getClientIp(), 'notify_url' => $this->config['notify_url'], 'trade_type' => 'JSAPI', 'openid' => $openid, ]; $params['sign'] = $this->buildSign($params, $this->config['api_key']); $xml = $this->arrayToXml($params); $responseXml = $this->postXml($url, $xml); $response = $this->xmlToArray($responseXml); if ($response['return_code'] == 'SUCCESS' && $response['result_code'] == 'SUCCESS') { return $this->buildJsApiParams($response['prepay_id']); } // 记录错误信息 $this->log('unifiedorder failed: ' . json_encode($response, JSON_UNESCAPED_UNICODE)); throw new Exception('统一下单失败: ' . $response['return_msg']); }

这里有一个细节：total_fee必须传整数分，不能是小数。如果订单金额是 13.8 元，传的是1380，不是13.8。另外body参数不要传太长，微信文档建议尽量短，部分场景下过长会被拦下来。

统一下单成功后会拿到prepay_id，紧接着要构造小程序端拉起支付需要的参数：

private function buildJsApiParams($prepayId) { $params = [ 'appId' => $this->config['appid'], 'timeStamp' => (string)time(), 'nonceStr' => $this->createNonceStr(), 'package' => 'prepay_id=' . $prepayId, 'signType' => 'MD5', ]; $params['paySign'] = $this->buildSign($params, $this->config['api_key']); return $params; }

小程序端拿到这个数组后，直接传给wx.requestPayment即可。timeStamp在签名时用的是字符串，传给小程序时也必须是字符串，很多前端报invalid timeStamp就是因为传成了数字类型。

2.3 签名机制与常见理解误区

签名本质上是为了防止参数被篡改。微信收到请求后，会把你送来的参数除sign之外全部取出来，自己做一次同样的排序拼接和 MD5，然后和你的sign比对。只要有一个参数不一致，或者双方约定的api_key不一样，签名结果就完全不同。这也是为什么SIGNERROR多半是 key 不对，或者参数顺序、大小写、数值类型不一致。

签名拼接时要注意：直接使用参数原值就行，不要对中文或者特殊字符先做urlencode，也不要转 HTML 实体。很多同学在构造body时喜欢写中文标点、空格，到验签时两边因为编码差异产生不一致，非常难排查。我的建议是把body等参数控制在常规字符范围内，回调地址用全小写字母，减少不必要的差异。

另外需要提一下 APIv3。如果你是新注册的商户，微信正逐步要求使用 APIv3 协议，v3 使用证书做身份认证，签名方式是请求头里面带时间戳、随机串和 SHA256-RSA 签名，报文体也从 XML 变成了 JSON。本文里的写法是 APIv2，但整体流程仍是下单、签名、回调、验签。老项目用 v2 很常见，新项目建议优先用官方 SDK。原理上的区别是：v2 用对称密钥api_key保证消息完整性，v3 用非对称证书保证身份安全，v3 在密钥泄漏风险上更低一些。

3. 支付回调处理与订单状态更新

3.1 接收回调并返回微信正确响应

微信支付结果通知是异步 POST 请求，请求体是 XML，所以后端必须用php://input读取原始报文，不能直接用$_POST，因为微信发送的不是普通表单格式。回调地址对应微擎模块里的某个入口方法，在module.php里实现一个公开方法即可。

基础接收代码如下：

public function doPageNotify() { $xml = file_get_contents('php://input'); // 先记录原始报文，排障全靠它 WeUtility::logging('wechat_notify', $xml); $data = $this->xmlToArray($xml); if (!$this->verifySign($data)) { echo $this->xmlResult('FAIL', '签名失败'); return; } try { $this->processPaidOrder($data); } catch (Exception $e) { WeUtility::logging('notify_error', $e->getMessage()); echo $this->xmlResult('FAIL', '业务处理失败'); return; } echo $this->xmlResult('SUCCESS', 'OK'); }

xmlResult返回固定格式的 XML：

private function xmlResult($code, $msg) { return "<xml><return_code><![CDATA[$code]]></return_code><return_msg><![CDATA[$msg]]></return_msg></xml>"; }

微信回调有一套重试机制，如果它收到FAIL或超时，会在后续一段时间内反复发送通知，最多重试几次。所以你的回调方法里必须保证幂等，也就是说同一条通知来了多次，后面的操作结果不能影响第一次已经完成的订单状态。

3.2 验签与订单核对

回调数据里的参数同样需要验签，验签方法和统一下单的签名方法完全一致。验签通过只是第一步，千万别直接更新订单状态，还要做三件事：

1. 检查out_trade_no对应的订单是否存在。

2. 检查total_fee是否等于订单应付金额。

3. 检查订单是否已经处于未支付状态。

三个条件都满足，才把订单更新为已支付。金额校验尤其重要，如果只看支付结果不看金额，一旦出现异常数据，对账时会很难看。一个微信回调报文的核心字段大概是这样的：

<xml> <appid>wx123456</appid> <mch_id>1600000000</mch_id> <out_trade_no>20250101001</out_trade_no> <transaction_id>420000123456</transaction_id> <total_fee>1380</total_fee> <result_code>SUCCESS</result_code> <time_end>20250101120000</time_end> </xml>

处理订单的代码：

public function processPaidOrder($data) { if ($data['return_code'] != 'SUCCESS' || $data['result_code'] != 'SUCCESS') { return; } $orderNo = $data['out_trade_no']; $order = pdo_get('your_order_table', ['out_trade_no' => $orderNo]); if (!$order) { throw new Exception('订单不存在: ' . $orderNo); } if (intval($data['total_fee']) !== intval($order['price'])) { throw new Exception('金额不一致，订单号: ' . $orderNo); } // 已经处理过的直接返回 if (intval($order['status']) !== 0) { return; } $affected = pdo_update( 'your_order_table', ['status' => 1, 'pay_time' => time()], ['id' => $order['id'], 'status' => 0] ); if (!$affected) { // 说明订单已经被并发更新过了 return; } // 在这里扣减库存、加销量等后续操作 }

3.3 防重与更新状态的关键细节

上面代码里最关键的是条件更新，pdo_update的第三个参数里带上'status' => 0，意思是只有当前订单还是未支付状态时才更新成已支付。如果影响行数为 0，说明已经被其他请求处理过了，直接返回成功即可。很多掉单、重复通知的坑，基本都是无条件UPDATE或先SELECT再UPDATE，并发时两个请求互相覆盖。

另一个细节是，更新订单状态和后续操作比如扣库存、加销量、发积分，最好放在一个事务里，或者用消息队列串行处理。如果扣库存抛异常，回调可以返回FAIL，微信会重试，此时订单状态仍然是未支付，不会产生“已付钱但库存没扣成功”的坏账。等系统恢复后下一轮回调再处理，流程就自愈了。

4. 常见问题排查与调试技巧

4.1 支付接口高频报错对照表

我把实际开发中遇到最多的微信支付报错整理成一个对照表，排查时可以直接对号入座：

SIGNERROR是最多的坑。如果你只是换了一个环境调试，记得把商户后台的api_key也一起换了，很多人在本地和线上用不同的 key，结果生产环境跑得好好的，本地一调就报签名错误。

4.2 回调收不到时如何定位

优先检查统一下单请求里的notify_url是否满足微信要求：必须是公网可访问的 URL，不能带查询参数，路径不能是localhost或局域网内网地址。微信服务器不可能访问到你本机，所以本地调试时不要指望回调打到127.0.0.1。正确做法是部署到一台公网可访问的测试服务器，域名如果有 HTTPS 要求，也要确保证书有效。

然后是日志：在回调方法第一步就记录原始报文，第二步记录验签结果。如果连第一条日志都没有，说明回调根本没到，属于网络或回调地址问题；如果只有第一条没有第二条，说明解析或验签失败。我见过一种情况，notify_url路径被微擎的路由规则改写了，实际访问到的是另一个方法，这时候日志能帮你很快定位到底命中了哪个入口。

4.3 金额精度、订单号与唯一索引

金额单位是分，而且是整型。total_fee传10.5就是错误，必须传1050。在 PHP 里浮点数很容易产生精度问题，所以不要把价格用float计算，应该统一转成分后用int操作。比如购物车合计是 13.8 元，后台保存为1380分，小程序展示时再除以 100 保留两位小数。

订单号生成要保证全局唯一，常见做法是时间戳加随机串：

$orderNo = date('YmdHis') . str_pad(mt_rand(1, 9999), 4, '0', STR_PAD_LEFT);

也可以加上用户 ID，但要注意商户订单号在微信侧不能超过 32 位。订单号在数据库里一定要建唯一索引，否则高并发下可能出现两条相同订单号同时插入成功，后面查单、对账全乱套。

4.4 调试开关与本地模拟回调

我习惯在支付类里加一个debug开关，开启后把每次请求的参数、响应、签名原串都写入独立日志文件。可以用微擎自带的日志方法，也可以直接写到data/pay_log/目录。开启 debug 后你会发现，大多数支付问题不需要猜，看一眼日志就清楚了。

另一个实用技巧是写一个本地脚本模拟微信回调，把回调报文构造出来 POST 到你的notify_url，用来测试幂等处理。但要注意，生产环境不要把这个口子放开，否则别人伪造通知也能进来。测试时临时跳过验签可以，上线前必须把验签和金额校验都打开。

5. 退款与售后支付逻辑扩展

5.1 退款接口与证书配置

用户申请退款时，后端调用微信支付的退款接口把已支付金额原路退回去。退款接口和统一下单不同，它要求双向证书认证，所以需要先从微信商户平台下载证书，放到服务器安全目录中。

退款接口请求地址是https://api.mch.weixin.qq.com/secapi/pay/refund，参数包括订单号、退款单号、订单金额、退款金额等，其中退款金额不能超过订单实际支付金额。实现大致如下：

public function refund($orderNo, $refundNo, $totalFee, $refundFee) { $url = 'https://api.mch.weixin.qq.com/secapi/pay/refund'; $params = [ 'appid' => $this->config['appid'], 'mch_id' => $this->config['mch_id'], 'nonce_str' => $this->createNonceStr(), 'out_trade_no' => $orderNo, 'out_refund_no' => $refundNo, 'total_fee' => intval($totalFee), 'refund_fee' => intval($refundFee), ]; $params['sign'] = $this->buildSign($params, $this->config['api_key']); $xml = $this->arrayToXml($params); $ch = curl_init($url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $xml); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_SSLCERT, $this->config['cert_path']); curl_setopt($ch, CURLOPT_SSLKEY, $this->config['key_path']); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); if (curl_errno($ch)) { throw new Exception('退款请求失败: ' . curl_error($ch)); } curl_close($ch); $responseArray = $this->xmlToArray($response); $this->log('refund response: ' . $response); return $responseArray; }

证书文件路径要注意两点：一是服务器要能正确读取文件，二是文件权限不要设置得过宽，建议证书权限设为600，只有运行 PHP 的系统用户能读。很多人把证书放到 web 可访问目录里，这相当于把支付密钥挂到公网上，风险很大。

5.2 关闭订单与定时补单

超过一定时间未支付的订单，建议调用微信的关闭订单接口，把订单关闭并释放库存。微信支付有一个pay/closeorder接口，传入out_trade_no即可，调用成功后会返回SUCCESS。订单关闭后不能再用同一个订单号发起支付，所以关单前要确保用户已经放弃支付。

除了主动关单，订单查询接口也很重要。用户重新进入订单页时，可以调pay/orderquery查询真实支付状态，把漏掉的回调补回来：

public function queryOrder($orderNo) { $url = 'https://api.mch.weixin.qq.com/pay/orderquery'; $params = [ 'appid' => $this->config['appid'], 'mch_id' => $this->config['mch_id'], 'out_trade_no' => $orderNo, 'nonce_str' => $this->createNonceStr(), ]; $params['sign'] = $this->buildSign($params, $this->config['api_key']); $xml = $this->arrayToXml($params); $responseXml = $this->postXml($url, $xml); $response = $this->xmlToArray($responseXml); if ($response['trade_state'] == 'SUCCESS') { // 补更新订单状态，同样要幂等处理 } return $response; }

定时任务可以用微擎框架的定时任务机制，每小时扫描那些支付状态未知、已经超时的订单，先调查询接口确认状态，再决定是关单还是补单。这样即使回调丢失，也不会一直卡着用户。

5.3 支付流水表与对账

涉及资金的功能，一定要有对账机制。我建议独立建一张支付流水表，不要把支付信息只堆在订单表里。每次发起支付写入一条待支付流水，支付回调成功后更新流水状态，退款也记录成另一条流水或同一个流水的状态变更。简单的流水表设计如下：

有了这张表，处理售后、对账和异常定位都会轻松很多。每天从微信商户平台下载对账单，和本地流水比对，发现差异时能直接定位到具体订单，人工判断处理方式。对账单下载接口是pay/downloadbill，按日下载，返回格式是文本，需要单独解析。

微信支付后端并没有太多高深的东西，真正决定项目成败的往往是回调幂等、日志记录和金额精度这些基础功夫。你与其花时间研究各种营销玩法，不如先把一条完整支付链路的所有日志打通、把订单状态机画明白，这样后面接退款、做对账都会非常顺。如果你现在正被某个支付报错卡住，先别急着改代码，翻一下日志里的签名原串和回调原文，大多数问题都能在十分钟内定位。