企业官网建设流程全解析

简介：PHP微信支付V3完整实例是一套面向PHP开发者的微信支付集成方案，适合需要在商城、小程序或业务系统中快速接入最新版微信支付接口的初中级开发者。资源围绕V3版统一下单、前端调起支付、异步回调通知、订单查询确认及退款等核心流程展开，并重点讲解了新版API签名规则与证书管理方式，同时给出沙箱测试与安全性方面的注意事项。压缩包共16个文件，以PHP脚本、ASP辅助文件、PEM证书、Access数据库及说明文档为主，整体仅61KB，轻量便于部署调试。示例代码中保留了证书配置、支付接口、订单回调及测试用数据库，配合txt说明可对照理解完整调用逻辑与配置文件结构。该资源已有4621人学习下载，适合想快速上手微信支付V3并落地到实际项目的PHP开发者参考。

1. PHP微信支付v3 完整实例：为什么官方文档读懂了还会翻车

「PHP微信支付v3 完整实例」最容易被误读的地方在于：它不是一个官方demo的搬运。很多PHP项目至今还停在v2的支付类写法，改个URL和字段名就指望跑通v3，结果第一次下单就被「签名错误」「证书序列号无效」卡住。v3把安全模型整个换掉了——请求签名从MD5变成SHA256withRSA，回调解密从「一把密钥走天下」变成「商户证书+平台证书+AES-256-GCM」三件套，接口路径也全部带上了/v3前缀。这篇按我接单的真实流程走一遍：商户平台该准备哪四样配置，PHP签名工具类怎么写，Native和JSAPI的下单差别，回调验签解密后如何安全落库，再单独列几个花过真金白银踩到的坑。适合正在用Laravel、ThinkPHP或原生PHP接微信支付v3的开发者。

2. 先搞懂v3的签名与证书体系：v2和v3差在哪，密钥从哪来

微信支付v3（官方叫APIv3）最难的不是接口本身，而是它换了整套安全体系。v2时代一个API密钥走天下，签名用MD5，回调内容用API密钥做AES解密，逻辑简单但密钥一旦泄露，伪造订单和偷看交易数据都能做到。v3把这件事拆成三把钥匙：商户私钥只管「发出去的请求签名」，平台证书管「收到的响应验签」，APIv3密钥单独管「回调密文解密」。分开了以后，每一把钥匙泄露的攻击面都可控得多，这也是官方文档一再强调「不要复用密钥」的原因。

2.1 APIv3的核心安全模型：双证书、双密钥与敏感字段加密

微信支付v3的安全模型可以概括为「双证书、双密钥」。双证书指的是商户API证书和微信支付平台证书：商户API证书用来证明「发起请求的是你」，平台证书用来证明「响应和回调真的来自微信支付」。双密钥指的是商户私钥和APIv3密钥：商户私钥用于给请求签名、解密敏感信息，APIv3密钥用于解密回调里的resource字段。

v2和v3的差异，用一张表可以看得很清楚：

为什么v3要这么绕？v2的API密钥本质上是单一对称密钥，既能验签又能解密，泄露一次就全线崩溃。v3把「签名」和「解密」两个职责拆开：即使APIv3密钥泄露，攻击者也只能解密回调数据，没法伪造一个合法的下单请求；反过来商户私钥泄露，签名会被伪造，但回调密文仍然解不开。

除了请求签名和回调验签，APIv3还约定了一类特殊字段的加密：凡涉及手机号、银行卡号等敏感信息，请求体里要上传用平台证书公钥加密后的密文，再配合商户私钥解密。这个机制在日常支付下单场景里用得不多，但做电商实名认证、代付时会碰到，知道有这个约定就行。

2.2 商户平台只需要四样东西：私钥、证书序列号、APIv3密钥、平台证书

真正接入前，先把商户平台的配置凑齐。登录微信支付商户平台，进入「账户中心-API安全」，找到APIv3密钥、商户API证书、平台证书三个入口。配置项一共四样：

这里有个容易忽略的点：APIv3密钥不是微信发给你的一串密码，而是你在商户平台「设置APIv3密钥」时自己填的32位字符。填完之后它不会在平台里再次显示，忘了只能重置。重置会立即使旧密钥失效，所以要么存进密码管理器，要么写进部署环境的.env。

商户API证书在平台里下载下来是p12格式，文件名通常是apiclient_cert.p12，里面同时含证书和私钥。网上有些教程让把p12直接传给PHP的openssl_pkcs12_read，但实际项目里更通用、更好维护的做法是用openssl命令转成两个pem文件，一个存证书、一个存私钥。转换命令我在第3章给出。

2.3 官方签名算法一步步拆解：Authorization头的真实构成

APIv3的请求签名不是简单地把参数排序后拼一个字符串，而是固定格式的消息串加RSA签名。先看最终产物——每次请求都要带一个Authorization头：

WECHATPAY2-SHA256-RSA2048 mchid="1900000001",nonce_str="b3f2...",signature="base64...",timestamp="1700000000",serial_no="3344AABBCCDDEEFF"

这个头里六个字段一个都不能少：mchid是商户号，nonce_str是本次请求的随机串，signature是RSA签名结果，timestamp是Unix时间戳，serial_no是商户API证书序列号。微信支付服务端拿到请求后，会先取serial_no找到对应的商户证书公钥，再按同样的规则拼出消息串，用公钥验证signature。

消息串的拼接规则是五段，每段用换行符分隔：请求方法、URL路径（含query参数）、时间戳、随机串、请求体。我最早调试时经常漏掉最后一行的换行符，导致签名不一致。代码实现如下：

$method = 'POST'; $url = '/v3/pay/transactions/native'; $timestamp = time(); $nonce = bin2hex(random_bytes(16)); $body = '{"appid":"wx1234567890abcdef","mchid":"1900000001","description":"测试商品","out_trade_no":"20250101220001","notify_url":"https://example.com/notify","amount":{"total":1,"currency":"CNY"}}'; $message = $method . "\n" . $url . "\n" . $timestamp . "\n" . $nonce . "\n" . $body . "\n"; $privateKey = file_get_contents('/path/to/apiclient_key.pem'); openssl_sign($message, $signature, $privateKey, OPENSSL_ALGO_SHA256); $authorization = sprintf( 'WECHATPAY2-SHA256-RSA2048 mchid="%s",nonce_str="%s",signature="%s",timestamp="%d",serial_no="%s"', '1900000001', $nonce, base64_encode($signature), $timestamp, '3344AABBCCDDEEFF' );

代码里的$url只取路径部分，不带scheme和域名。这里的时间戳和后端校验的时间误差必须控制在几分钟内，服务器时间漂移大了会直接返回401。另外要注意，网上搜得到一堆php hmacsha256算签名的旧代码，那是v2的算法，v3的签名类型是SHA256-RSA2048，算法和消息串结构完全不同，直接套用只会越改越乱。

官方文档里还藏着一个换证书的坑：如果重新生成过商户API证书，serial_no会变，Authorization头里必须同步更新。用旧serial_no配合新私钥去签名，微信支付也会校验失败。所以证书文件更新后，第一件事就是跑一遍读取序列号的命令，把配置里的serial_no换掉。

3. 写一个能用的PHP签名工具类：私钥转pem、Authorization头与验签

签名逻辑不要散落在各个业务方法里，独立成一个PHP类是最小成本的做法。这一章从证书准备开始，到请求签名、应答验签，给一套可以直接放进项目使用的类。我把文件路径全部收进构造函数，方便在Laravel的config配置里读取，ThinkPHP或原生PHP也能直接new。

3.1 用openssl命令把p12转成pem，并读取证书序列号

商户平台下载的apiclient_cert.p12是证书+私钥的打包文件，PHP的openssl扩展虽然支持直接读取p12，但需要额外管理一个证书密码字符串，不如转成pem干净。下载后先在本地执行两条命令：

openssl pkcs12 -in apiclient_cert.p12 -clcerts -nokeys -out apiclient_cert.pem openssl pkcs12 -in apiclient_cert.p12 -nocerts -nodes -out apiclient_key.pem chmod 600 apiclient_key.pem

第一条命令导出证书，第二条导出私钥。转换过程中会要求输入p12的密码，默认是商户号，如果下载时设置过其他密码就用自己设置的。导出后用下面这条命令读证书序列号：

openssl x509 -in apiclient_cert.pem -noout -serial

输出形如serial=3344AABBCCDDEEFF，把serial=前缀去掉，得到的3344AABBCCDDEEFF就是Authorization头里的serial_no。注意这个序列号是十六进制串，不要带冒号，微信支付服务端不接受类似33:44:AA:BB这种带分隔符的格式。转换完成后，apiclient_cert.pem和apiclient_key.pem两个文件放进服务器的存储目录，建议放在项目外部、确保不能被web目录访问。apiclient_key.pem本质上是私钥文件，权限至少600，不要提交进Git仓库。

3.2 PHP签名工具类：Authorization头与请求体签名

把上面的逻辑整理成一个类。构造函数接收五样配置，buildAuthorization方法负责生成签名和Authorization头：

<?php class WxPayV3Client { private string $mchId; private string $serialNo; private string $privateKeyPath; private string $apiV3Key; private string $platformCertPath; public function __construct(array $config) { $this->mchId = $config['mch_id']; $this->serialNo = $config['serial_no']; $this->privateKeyPath = $config['private_key_path']; $this->apiV3Key = $config['api_v3_key']; $this->platformCertPath = $config['platform_cert_path']; } public function buildAuthorization(string $method, string $url, string $body): string { $timestamp = time(); $nonceStr = bin2hex(random_bytes(16)); $message = $method . "\n" . $url . "\n" . $timestamp . "\n" . $nonceStr . "\n" . $body . "\n"; openssl_sign( $message, $signature, file_get_contents($this->privateKeyPath), OPENSSL_ALGO_SHA256 ); return sprintf( 'WECHATPAY2-SHA256-RSA2048 mchid="%s",nonce_str="%s",signature="%s",timestamp="%d",serial_no="%s"', $this->mchId, $nonceStr, base64_encode($signature), $timestamp, $this->serialNo ); } }

buildAuthorization的参数有讲究：$method必须是GET、POST、PATCH、DELETE里的大写形式；$url是路径和query，不要把完整域名传进来；$body是序列化后的请求体字符串，如果请求没有body就传空字符串。这个方法每次调用都会读一次私钥文件，对支付接口的调用频率来说完全够用，不需要做文件缓存。这个类里的apiV3Key和platformCertPath现在还没用到，它们在回调解密和验签环节发挥作用。把配置和依赖都收进构造函数的好处是，后续在Laravel的ServiceProvider里绑定单例，或者在一个普通项目中new一次传给Guzzle中间件，都很方便。

3.3 应答验签与回调验签：平台证书的加载与验证

v3要求对微信支付返回的响应也要验签，验证「这个响应真的是微信支付发出来的」。响应头里带Wechatpay-Timestamp、Wechatpay-Nonce、Wechatpay-Signature、Wechatpay-Serial四个字段，验签逻辑如下：

public function verifyWechatpaySignature(array $headers, string $body): bool { $timestamp = $headers['Wechatpay-Timestamp'] ?? ''; $nonce = $headers['Wechatpay-Nonce'] ?? ''; $signature = $headers['Wechatpay-Signature'] ?? ''; $serial = $headers['Wechatpay-Serial'] ?? ''; if ($serial !== $this->platformSerialNo) { return false; } $message = $timestamp . "\n" . $nonce . "\n" . $body . "\n"; $publicKey = openssl_pkey_get_public(file_get_contents($this->platformCertPath)); return openssl_verify($message, base64_decode($signature), $publicKey, OPENSSL_ALGO_SHA256) === 1; }

这段代码同时适用于「下单接口的响应」和「异步通知的请求」：验签消息串永远是时间戳+换行+随机串+换行+请求体（响应体）+换行。body参数在响应验签时传响应体字符串，在回调验签时传原始请求体字符串。注意PHP里处理HTTP头时，原生环境下的$_SERVER会把header名转成大写并加HTTP_前缀，比如HTTP_WECHATPAY_TIMESTAMP，取值时要做一层兼容转换，或者直接用Laravel的request对象去取。

我在类里加了一个platformSerialNo的判断，目的是防止有人把平台证书路径配错成商户证书，导致验签永远失败。有些项目下载平台证书之后不校验序列号，等到出问题才发现证书文件不对，那时候已经排查了很久了。平台证书建议放在项目配置目录之外，和商户私钥一样按敏感文件处理。

4. 拉起支付到收到回调：Native下单、JSAPI下单与异步通知完整代码

这一章把支付全链路串起来。Native支付适合PC网站，用户扫码支付；JSAPI支付适合公众号H5和小程序，需要拿到openid。两条链路的下单接口不同，但签名、验签、解密方法完全复用上一章的类。

4.1 Native下单：从构造请求到拿到code_url

Native支付的下单接口是POST /v3/pay/transactions/native。请求体里核心字段有appid、mchid、description、out_trade_no、notify_url、amount，其中amount里total的单位是「分」，这是v3和很多开发者本地习惯的「元」最大的冲突点。先看完整实例代码：

$client = new WxPayV3Client($config); $data = [ 'appid' => $config['app_id'], 'mchid' => $config['mch_id'], 'description' => '商品描述', 'out_trade_no' => '20250101220001', 'notify_url' => 'https://example.com/notify.php', 'amount' => [ 'total' => 1, 'currency' => 'CNY' ], ]; $url = 'https://api.mch.weixin.qq.com/v3/pay/transactions/native'; $body = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES); $authorization = $client->buildAuthorization('POST', '/v3/pay/transactions/native', $body); $ch = curl_init($url); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST'); curl_setopt($ch, CURLOPT_POSTFIELDS, $body); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Authorization: ' . $authorization, 'Content-Type: application/json', 'Accept: application/json', ]); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_TIMEOUT, 10); $response = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch);

json_encode时加上JSON_UNESCAPED_UNICODE和JSON_UNESCAPED_SLASHES，是为了让请求体里的中文和斜杠保持原样，避免微信服务端拼消息串时因为转义差异导致签名不一致。签名时用的URL路径和curl实际请求的URL要完全一致，都是/v3/pay/transactions/native，不能一个带域名一个不带。请求成功返回的HTTP状态码是200，响应体里有code_url字段，值类似weixin://wxpay/bizpayurl?pr=xxxx。把这个字符串生成二维码，用户扫码后会拉起微信收银台。如果返回非200，响应体会带code和message，比如NO_AUTH、PARAM_ERROR，把message打日志比猜原因快得多。

4.2 JSAPI下单与小程序支付：参数差异与prepay_id

JSAPI下单接口是POST /v3/pay/transactions/jsapi，请求体在Native基础上多一个payer字段：

$data = [ 'appid' => $config['app_id'], 'mchid' => $config['mch_id'], 'description' => '商品描述', 'out_trade_no' => '20250101220001', 'notify_url' => 'https://example.com/notify.php', 'amount' => [ 'total' => 1, 'currency' => 'CNY' ], 'payer' => [ 'openid' => $openid ] ];

公众号里通过网页授权拿openid，小程序里通过wx.login加code2Session接口拿openid，两者最终都是同一个openid。下单成功后返回prepay_id，这个prepay_id要拼进前端调起支付时的package参数。拿到prepay_id后，需要再生成一份给前端JS调用的签名参数paySign。这个签名串的格式和Authorization头完全不同，它是一段以appId开头的四段消息串：

$params = [ 'appId' => $config['app_id'], 'timeStamp' => (string) time(), 'nonceStr' => bin2hex(random_bytes(16)), 'package' => 'prepay_id=' . $prepayId, 'signType' => 'RSA', ]; $message = $params['appId'] . "\n" . $params['timeStamp'] . "\n" . $params['nonceStr'] . "\n" . $params['package'] . "\n"; openssl_sign($message, $paySign, file_get_contents($config['private_key_path']), OPENSSL_ALGO_SHA256); $params['paySign'] = base64_encode($paySign);

这里有一个高频错误：消息串里的timeStamp必须是字符串，和Authorization签名里的整数时间戳不同，调起支付参数要求它作为字符串参与拼接和传给前端。另外paySign用的是同一把商户私钥，但算法是SHA256withRSA，signType固定写RSA，小程序端wx.requestPayment会自己按signType解析。小程序端如果报「用户态签名signature错误」，优先检查这里的时间戳类型、nonceStr长度和package前缀，这三处错一个都会验签失败。用uniapp打包App时，App支付走的是APP支付接口而不是JSAPI，参数不完全一样，建议按App支付单独写一套下单逻辑。

4.3 异步通知回调：验签、解密、更新订单状态

支付成功后微信支付会向notify_url发起异步通知，body是JSON，resource字段里是加密后的交易数据。处理顺序有硬性要求：先验签、再解密、再更新订单、最后返回SUCCESS给微信支付。颠倒任何一步都可能导致重复通知或订单状态错乱。

$headers = getallheaders(); $body = file_get_contents('php://input'); $payload = json_decode($body, true); if (!$client->verifyWechatpaySignature($headers, $body)) { http_response_code(401); exit('verify failed'); } $resource = $payload['resource']; $ciphertext = base64_decode($resource['ciphertext']); $tag = substr($ciphertext, -16); $ciphertext = substr($ciphertext, 0, -16); $decrypted = openssl_decrypt( $ciphertext, 'aes-256-gcm', $config['api_v3_key'], OPENSSL_RAW_DATA, $resource['nonce'], $tag, $resource['associated_data'] ?? '' );

注意：微信支付v3的AES-256-GCM密文格式是「密文+16字节认证标签（tag）」，直接拿整个ciphertext丢给openssl_decrypt会解密失败。必须先截出最后16字节作为tag，剩下的才是真正的密文。

解密成功后的JSON里包含out_trade_no、transaction_id、trade_state、amount等关键字段。这里trade_state为SUCCESS才代表支付成功，其他状态如REFUND、CLOSED要分开处理。落库的逻辑我建议：先查订单，如果已经处于已支付状态，直接返回SUCCESS，不做重复更新；否则更新订单状态、记录transaction_id，然后返回：

{"code": "SUCCESS", "message": "成功"}

返回这个JSON时HTTP状态码用200，微信支付收到后才会停止重试通知。如果验签失败或解密失败，返回非200或非SUCCESS的JSON，微信支付会按它自己的重试策略继续通知，通常是间隔递增地重试几次。

5. 微信支付v3避坑手册：证书序列号、金额单位与回调幂等的5个真实教训

这一章是我做支付集成时踩过的坑，每条都花了真金白银或小半天时间去查。按现象、原因、解决的顺序写，排查时可以对照着看。

5.1 证书序列号错一位，签名全部失效

现象：首次下单返回401，响应体里提示证书序列号不正确或签名无效。 原因：Authorization头里的serial_no填成证书文件名，或者从openssl读取结果里没去掉serial=前缀，或者把平台证书序列号当成了商户证书序列号。这三类错误都会让微信支付找不到对应公钥。 解决：用openssl x509 -in apiclient_cert.pem -noout -serial命令读取商户证书序列号，去掉前缀后存成配置项。平台证书的序列号是响应头里的Wechatpay-Serial，两者用途不同，别混。

5.2 本地能跑通线上报签名错误：URL不一致是最大玄学

现象：同样的签名工具类，本地调试一切正常，部署到服务器后所有请求都报「签名错误」。 原因：签名串里的URL和实际请求URL不一致。常见于框架把URL做了Rewrite、反向代理加了前缀、或者请求uri里query参数顺序在不同环境下被重排。 解决：加一行日志，打印签名用的URL和curl实际请求的URL。用Guzzle的话直接取$request->getUri()，不要自己拼字符串。注意query参数要按原样拼在URL里，包括顺序。

5.3 金额单位：分和元又双叒搞错

现象：用户支付1元，订单金额记录成1分，对账时发现账目不平。 原因：v3的amount.total单位是整数分，v2也是分。很多从旧系统迁移来的代码里total字段习惯存元，直接喂给v3接口。 解决：数据库金额字段用整数分存储，下单和回调全程用分，只在接口返回前端时转成元。下单前加一个校验：金额必须是大于0的整数。

5.4 回调重复通知：幂等没做，库存扣两次

现象：同一笔订单收到三次通知，每次进入业务逻辑都执行了库存扣减。 原因：微信支付的通知有重试机制，收到非SUCCESS或超时会按递增间隔重试；本地调试时手动重放请求也会触发。 解决：回调入口先按out_trade_no查询订单状态，已支付就直接返回SUCCESS。更新订单状态时用乐观锁或状态条件更新，确认只有一次能从未支付翻转为已支付。

5.5 平台证书过期：验签突然全挂

现象：某天开始所有回调验签失败，接口返回401，业务方反馈收不到支付结果。 原因：平台证书有有效期，过期后微信支付会用新证书签名，代码里还是旧的pem文件。 解决：不要手动下载平台证书写死路径。用GET /v3/certificates接口定期拉取并更新，或者用官方PHP SDK的证书管理器自动刷新。最少也要在验签失败时记录Wechatpay-Serial，和本地pem的序列号对比，几秒钟就能确认是不是证书过期。

6. 进阶：把签名、验签、日志封装成Guzzle中间件，一次配置到处复用

集成微信支付v3的项目，常见的坏味道是每个Controller里都写一遍curl + 签名 + 验签。业务一多，签名代码复制得到处是，某天改一次证书路径就要全局搜索。我的习惯是把签名、验签和日志收敛到Guzzle中间件里，Controller只管下单和收回调。

6.1 用Guzzle中间件统一处理Authorization头

用Guzzle时，请求体是Stream，读了之后不会自动倒带。中间件里先getContents()拿body，签名完再rewind()放回去，不然下一步请求发出去body是空的。

use GuzzleHttp\Client; use GuzzleHttp\HandlerStack; use GuzzleHttp\Middleware; use Psr\Http\Message\RequestInterface; $stack = HandlerStack::create(); $stack->push(Middleware::mapRequest(function (RequestInterface $request) use ($signer) { $uri = $request->getUri(); $url = $uri->getPath(); if ($uri->getQuery() !== '') { $url .= '?' . $uri->getQuery(); } $body = $request->getBody()->getContents(); $request->getBody()->rewind(); return $request->withHeader('Authorization', $signer->buildAuthorization($request->getMethod(), $url, $body)); })); $client = new Client([ 'base_uri' => 'https://api.mch.weixin.qq.com', 'handler' => $stack, 'timeout' => 10, ]);

url这里拿的是path+query，正好就是签名串要求的URL片段。这个方法同样适用于JSAPI下单、查单、退款等所有v3接口，Controller不用再关心Authorization。

6.2 请求响应日志：排障黑匣子变透明

中间件里再加一个tap，把每次请求的URL、请求体、响应状态码、响应体、验签结果写进日志文件。我排障时看得最多的不是框架日志，而是这一条记录。有一次线上回调验签全失败，就是靠日志里对比Wechatpay-Serial和本地平台证书序列号，发现证书已经在凌晨过期。

$stack->push(Middleware::tap(function ($request, $options) { \Log::info('[wxpay] request', [ 'url' => (string) $request->getUri(), 'body' => $request->getBody()->getContents(), ]); $request->getBody()->rewind(); }));

6.3 验证全链路：仿真环境优先，1分钱垫底

能申请到微信支付仿真测试环境的，先在沙箱里把下单、回调验签、解密、幂等全跑通，再切生产。没有沙箱的，找一个低频商品用1分钱真实订单做端到端验证，下单后仔细核对回调里的out_trade_no、trade_state和amount，再确认本地订单状态已经翻转。

我现在的习惯是把签名器、下单、验签解密、中间件四段做成一套固定模板，新项目直接复制改配置，两小时就能跑通一笔支付。这个方向投入产出比很高，希望帮到你。

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