简介本资源是面向PHP后端开发者与微信支付接入初学者的V3版本完整实践方案聚焦于最新微信支付接口的安全集成与全流程落地。资源包含统一下单、前端调起、异步回调、订单查询、退款处理及沙箱测试等核心环节的可运行代码与配置说明覆盖证书管理、API签名HMAC-SHA256、敏感信息防护等关键安全实践。压缩包共16个文件以3个核心PHP文件payapi.php、sslapi.php、pemapi.php实现服务端逻辑7个ASP文件如pay_V3.asp、notify.asp提供兼容性支持辅以2个说明文档、1个PEM证书、1个JS脚本及GIF加载动画等整体仅61KB轻量易部署。已有4657人学习下载读者可直接复用目录结构与模块化代码快速搭建调试环境掌握从商户配置、签名生成到支付闭环的完整链路尤其适合中小项目快速接入与教学演示。1. PHP微信支付v3完整实例不是配个密钥就能跑通的黑匣子而是要过证书校验、签名生成、回调验签、退款幂等四道关的生产级闭环你是不是也试过照着微信官方文档改完appid和mchidcurl 一发下单接口就返回401 Unauthorized或者调试回调时发现WechatPay-Signature总是验不过日志里只有一行invalid signature连哪一步出错都看不到这不是你代码写错了——这是微信支付 v3 的真实水深它把安全逻辑从「可选配置」变成了「强制门禁」。这份 PHP 微信支付 v3 完整实例不是教你怎么调通一个接口而是把从证书加载、私钥签名、HTTP 头构造、响应解密到异步通知验签、退款状态轮询、订单超时关闭这一整条链路全部拆成可执行、可调试、可复现的 PHP 原生代码不依赖 SDK 封装覆盖JSAPI公众号/小程序、NATIVE扫码、APP三类主流支付场景。适合正在上线微信支付、被回调验签卡住、或需要脱离 SDK 自主控制签名流程的后端开发者。它不讲 OAuth2 流程不画架构图只给你能php -S起来、用 Postman 打点、看得到X-Wechat-Request-ID和Wechatpay-Serial的真实交互。2. 从零构建微信支付 v3 请求基础设施证书加载、私钥签名与 HTTP 头组装微信支付 v3 的通信安全基石是双向 TLS 平台证书签名。它要求你不仅持有自己的私钥还要正确加载微信平台的公钥证书并在每个请求头中注入动态签名。这不是file_get_contents()加个 header 就能搞定的事——稍有偏差401就会准时出现。下面这三步缺一不可且顺序不能乱。2.1 加载平台证书并提取公钥用于验签微信不会在每次响应中返回证书而是要求你提前下载并缓存其平台证书.pem格式。该证书由微信 CA 签发用于验证所有响应体的签名真实性。你必须先把它读入内存再用 OpenSSL 提取其中的公钥资源// certs/wechat_platform_cert.pem 是你从微信商户平台「API安全」页下载的平台证书 $platformCertPath __DIR__ . /certs/wechat_platform_cert.pem; if (!file_exists($platformCertPath)) { throw new RuntimeException(平台证书文件不存在请先从微信商户平台下载并放置于 certs/ 目录下); } // 读取证书内容 $certContent file_get_contents($platformCertPath); if (!$certContent) { throw new RuntimeException(无法读取平台证书内容); } // 解析 PEM 证书获取公钥资源注意不是私钥 $certResource openssl_x509_read($certContent); if (!$certResource) { throw new RuntimeException(无法解析平台证书openssl_x509_read 失败 . openssl_error_string()); } $publicKey openssl_pkey_get_public($certResource); if (!$publicKey) { throw new RuntimeException(无法从证书中提取公钥 . openssl_error_string()); }提示openssl_x509_read()返回的是 X.509 证书资源openssl_pkey_get_public()才真正拿到可用于验签的公钥资源。很多翻车案例是直接对$certContent调用openssl_verify()结果永远返回0—— 因为它需要的是pkey类型资源不是原始 PEM 字符串。2.2 使用商户私钥生成标准 v3 签名字符串微信 v3 签名不是对整个 JSON body 做 hash而是按严格顺序拼接「HTTP 方法 换行符 请求路径 换行符 时间戳 换行符 随机串 换行符 请求体 SHA256」再用你的商户私钥.pem格式进行 RSA-SHA256 签名。这个拼接规则必须一字不差否则签名必然失败function generateWechatV3Signature( string $method, string $urlPath, string $timestamp, string $nonceStr, string $body ): string { // 步骤1计算请求体的 SHA256空 body 也要算空字符串的 hash $bodyHash hash(sha256, $body, false); // 步骤2严格按顺序拼接注意每段后都有 \n包括最后一段 $message sprintf( %s\n%s\n%s\n%s\n%s\n, strtolower($method), $urlPath, $timestamp, $nonceStr, $bodyHash ); // 步骤3加载商户私钥certs/apiclient_key.pem需 chmod 600 $privateKeyPath __DIR__ . /certs/apiclient_key.pem; $privateKey file_get_contents($privateKeyPath); if (!$privateKey) { throw new RuntimeException(无法读取商户私钥文件); } $privateKeyResource openssl_pkey_get_private($privateKey, ); if (!$privateKeyResource) { throw new RuntimeException(无法加载私钥 . openssl_error_string()); } // 步骤4执行 RSA-SHA256 签名 $signature ; $result openssl_sign($message, $signature, $privateKeyResource, sha256); if (!$result) { throw new RuntimeException(签名失败 . openssl_error_string()); } // 步骤5base64 编码并返回注意微信要求原始二进制签名做 base64不是 hex return base64_encode($signature); }参数说明$method全大写如POST、GET微信校验时会转小写比对$urlPath仅 path 部分不含域名和 query如/v3/pay/transactions/jsapi$timestamp当前 Unix 时间戳秒级必须与请求头Wechatpay-Timestamp一致$nonceStr32 位随机字符串推荐bin2hex(random_bytes(16))必须与请求头Wechatpay-Nonce一致$body原始 JSON 字符串非格式化、无空格GET 请求传空字符串。2.3 组装符合 v3 规范的完整 HTTP 请求头微信 v3 要求四个固定 Header缺一不可且值必须与签名时使用的参数完全一致function buildWechatV3Headers(string $method, string $urlPath, string $body ): array { $timestamp (string) time(); $nonceStr bin2hex(random_bytes(16)); $signature generateWechatV3Signature($method, $urlPath, $timestamp, $nonceStr, $body); // 注意Authorization 头格式为固定字符串拼接字段间用英文逗号空格分隔 $authorization sprintf( WECHATPAY2-SHA256-RSA2048 mchid%s,nonce_str%s,signature%s,timestamp%s,serial_no%s, 1900000100, // 替换为你的真实商户号 mchid $nonceStr, $signature, $timestamp, 1234567890ABCDEF1234567890ABCDEF12345678 // 替换为你证书中的 serial_no见 certs/apiclient_cert.pem 头部 ); return [ Content-Type: application/json, Accept: application/json, Authorization: . $authorization, User-Agent: PHP-WechatPay-v3-Client/1.0, ]; }关键点serial_no不是你自己生成的而是从你的apiclient_cert.pem文件头部提取的证书序列号Subject: CN... serialNumber1234567890ABCDEF1234567890ABCDEF12345678。务必手动确认填错会导致401且错误信息不提示具体原因。3. 实战 JSAPI 支付下单从统一下单到前端唤起支付JSAPI 是公众号/小程序内最常用的支付方式。它的核心是后端调用/v3/pay/transactions/jsapi获取预支付交易会话标识prepay_id再将其签名后传给前端调用wx.requestPayment。整个过程必须保证时间戳、随机串、签名三者严格一致。3.1 构造 JSAPI 下单请求体含 openid 与商品信息微信 v3 要求请求体为标准 JSON且amount必须是整数单位分description不能含敏感词notify_url必须是 HTTPS 且已备案function buildJsapiOrderPayload(string $openId, string $outTradeNo): array { return [ appid wxd678efh567hg6787, // 替换为你的公众号 AppID mchid 1900000100, // 替换为你的商户号 description 测试商品PHP微信支付v3实例, out_trade_no $outTradeNo, // 商户系统内部订单号32字符内唯一 time_expire date(c, time() 3600), // ISO8601 格式建议 2 小时 attach demo_v3_jsapi, // 可选透传字段回调时原样返回 notify_url https://yourdomain.com/api/wechat/notify, // 必须 HTTPS goods_tag demo, // 可选商品标记 support_fapiao true, // 是否支持电子发票 amount [ total 1, // 总金额单位分1分钱测试 currency CNY ], payer [ openid $openId // 用户在公众号/小程序下的 openid ] ]; }注意out_trade_no是你系统内唯一订单号微信不校验格式但强烈建议用date(ymdHis) . mt_rand(1000,9999)生成避免重复time_expire必须是 ISO8601 格式带T和Z或时区date(c)是最稳妥选择。3.2 发起下单请求并解析预支付参数使用上一节封装的buildWechatV3Headers()和buildJsapiOrderPayload()组合发起 cURL 请求function requestJsapiOrder(string $openId): array { $outTradeNo date(ymdHis) . mt_rand(1000, 9999); $payload buildJsapiOrderPayload($openId, $outTradeNo); $bodyJson json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES); $url https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi; $headers buildWechatV3Headers(POST, /v3/pay/transactions/jsapi, $bodyJson); $ch curl_init(); curl_setopt_array($ch, [ CURLOPT_URL $url, CURLOPT_RETURNTRANSFER true, CURLOPT_POST true, CURLOPT_POSTFIELDS $bodyJson, CURLOPT_HTTPHEADER $headers, CURLOPT_SSL_VERIFYPEER true, CURLOPT_SSLCERT __DIR__ . /certs/apiclient_cert.pem, // 必须提供客户端证书 CURLOPT_SSLKEY __DIR__ . /certs/apiclient_key.pem, // 必须提供客户端私钥 CURLOPT_TIMEOUT 30, CURLOPT_HEADER false, ]); $response curl_exec($ch); $httpCode curl_getinfo($ch, CURLINFO_HTTP_CODE); $headerSize curl_getinfo($ch, CURLINFO_HEADER_SIZE); $header substr($response, 0, $headerSize); $body substr($response, $headerSize); curl_close($ch); if ($httpCode ! 200) { $errorData json_decode($body, true) ?: [raw_response $body]; throw new RuntimeException(下单失败 [{$httpCode}]: . json_encode($errorData, JSON_UNESCAPED_UNICODE)); } $responseData json_decode($body, true); if (!$responseData || !isset($responseData[prepay_id])) { throw new RuntimeException(响应数据异常未找到 prepay_id . $body); } // 返回给前端所需的所有参数含二次签名 return [ appId $payload[appid], timeStamp (string) time(), nonceStr bin2hex(random_bytes(16)), package prepay_id . $responseData[prepay_id], signType RSA, paySign generateJsapiPaySign($payload[appid], $responseData[prepay_id]), ]; } // JSAPI 前端调用 wx.requestPayment 所需的 paySign 是另一套签名规则非 v3 接口签名 function generateJsapiPaySign(string $appId, string $prepayId): string { $params [ appId $appId, timeStamp (string) time(), nonceStr bin2hex(random_bytes(16)), package prepay_id . $prepayId, signType RSA, ]; // 按字典序排序后拼接 keyvalue 形式注意末尾无 ksort($params); $string1 ; foreach ($params as $k $v) { $string1 . $k . . $v . ; } $string1 rtrim($string1, ); // 加上 API 密钥在商户平台「API安全」页设置 $apiKey your_merchant_api_key_here; // 替换为你的 API 密钥 $stringSignTemp $string1 . key . $apiKey; return strtoupper(md5($stringSignTemp)); }血泪经验generateJsapiPaySign()中的key是你在微信商户平台单独设置的「APIv3密钥」32位不是证书私钥也不是商户号。填错会导致前端requestPayment报invalid sign且错误日志极难定位。3.3 前端 JSAPI 唤起支付供验证用后端返回上述数组后前端只需// 假设 data 是后端返回的关联数组 wx.requestPayment({ timeStamp: data.timeStamp, nonceStr: data.nonceStr, package: data.package, signType: data.signType, paySign: data.paySign, success(res) { console.log(支付成功, res); }, fail(err) { console.error(支付失败, err); } });验证技巧首次调试时把amount.total设为11分钱避免误扣款同时打开微信开发者工具「调试」→「Network」观察requestPayment调用是否发出以及控制台是否有invalid sign报错。4. 异步通知验签与订单状态更新拒绝裸奔接收 notify_url微信支付的异步通知notify_url是唯一可信的支付成功凭证。你绝不能在用户点击「支付完成」后就认为交易成功——必须等待微信服务器 POST 到你的notify_url且你必须完成三重校验HTTPS、JSON 解密、平台证书验签。漏掉任何一环都可能造成资金损失。4.1 接收并解密通知原始加密体微信 v3 的通知体是 AES-256-GCM 加密的你必须用平台证书中的公钥解密function decryptWechatNotifyBody(string $encryptedBody, string $associatedData, string $nonce): string { $platformCertPath __DIR__ . /certs/wechat_platform_cert.pem; $certContent file_get_contents($platformCertPath); $certResource openssl_x509_read($certContent); $publicKey openssl_pkey_get_public($certResource); // 从平台证书中提取加密用的公钥注意不是验签用的同一把 $details openssl_x509_parse($certResource); if (empty($details[subject][CN]) || strpos($details[subject][CN], WeChat Pay) false) { throw new RuntimeException(平台证书不合法CN 不包含 WeChat Pay); } // 微信通知体是 base64 编码的密文需先解码 $cipherText base64_decode($encryptedBody); if ($cipherText false) { throw new RuntimeException(密文 base64 解码失败); } // AES-256-GCM 解密PHP 7.1 $decrypted openssl_decrypt( $cipherText, aes-256-gcm, $associatedData, // 这里是微信传来的 associated_data 字段非密钥 OPENSSL_RAW_DATA, $nonce, $tag // tag 由微信在 header 中提供需从 Wechatpay-Serial 等 header 提取 ); if ($decrypted false) { throw new RuntimeException(AES 解密失败 . openssl_error_string()); } return $decrypted; }关键点$associatedData和$nonce并非固定值而是微信在通知请求头中通过Wechatpay-Serial、Wechatpay-Nonce、Wechatpay-Signature等字段传递的。你必须先解析 header再传入解密函数。很多项目直接硬编码associatedData导致解密永远失败。4.2 完整 notify_url 入口处理逻辑含验签一个健壮的notify_url应该是原子操作接收 → 解密 → 验签 → 更新订单 → 返回成功响应。任意环节失败都必须返回200 OK{code:SUCCESS,message:OK}否则微信会持续重试// api/wechat/notify.php if ($_SERVER[REQUEST_METHOD] ! POST) { http_response_code(405); echo json_encode([code FAIL, message Method Not Allowed]); exit; } // 1. 获取原始 POST body不能用 $_POST它会自动解析 JSON 失败 $rawBody file_get_contents(php://input); if (!$rawBody) { http_response_code(400); echo json_encode([code FAIL, message Empty body]); exit; } // 2. 提取请求头中的关键字段 $wechatpaySerial $_SERVER[HTTP_WECHATPAY_SERIAL] ?? ; $wechatpayNonce $_SERVER[HTTP_WECHATPAY_NONCE] ?? ; $wechatpayTimestamp $_SERVER[HTTP_WECHATPAY_TIMESTAMP] ?? ; $wechatpaySignature $_SERVER[HTTP_WECHATPAY_SIGNATURE] ?? ; // 3. 构造验签消息与下单签名规则一致方法路径时间戳随机串body hash $message sprintf( POST\n/v3/notifications/callback\n%s\n%s\n%s\n, $wechatpayTimestamp, $wechatpayNonce, hash(sha256, $rawBody, false) ); // 4. 加载平台公钥并验签 $platformCertPath __DIR__ . /../certs/wechat_platform_cert.pem; $certContent file_get_contents($platformCertPath); $certResource openssl_x509_read($certContent); $publicKey openssl_pkey_get_public($certResource); $result openssl_verify($message, base64_decode($wechatpaySignature), $publicKey, sha256); if ($result ! 1) { error_log([Wechat Notify] 验签失败 . $message); http_response_code(401); echo json_encode([code FAIL, message Invalid signature]); exit; } // 5. 解密通知体 $notifyData json_decode($rawBody, true); if (!$notifyData || !isset($notifyData[resource])) { http_response_code(400); echo json_encode([code FAIL, message Invalid notify format]); exit; } $resource $notifyData[resource]; $decrypted decryptWechatNotifyBody( $resource[ciphertext], $resource[associated_data], $resource[nonce] ); $decryptedData json_decode($decrypted, true); if (!$decryptedData || !isset($decryptedData[transaction_id])) { http_response_code(400); echo json_encode([code FAIL, message Decrypt failed or invalid data]); exit; } // 6. 更新订单状态伪代码实际需连接数据库 $orderNo $decryptedData[out_trade_no] ?? ; $transactionId $decryptedData[transaction_id] ?? ; $amount $decryptedData[amount][total] ?? 0; $successTime $decryptedData[success_time] ?? date(Y-m-d H:i:s); // TODO: 根据 $orderNo 更新你数据库中订单状态为「已支付」记录 $transactionId 和 $successTime // 7. 返回微信要求的成功响应必须是 200 OK JSON http_response_code(200); echo json_encode([code SUCCESS, message OK]); exit;注意http_response_code(200)必须在echo之前调用否则微信可能认为响应失败echo的内容必须是{code:SUCCESS,message:OK}多一个空格、少一个引号都会触发重试。5. 避坑指南微信支付 v3 在 PHP 中最常踩的五个坑微信支付 v3 的文档严谨但隐晦很多错误现象和原因并不对应。以下是我在三个不同项目中反复验证过的五类高频问题每一条都附带真实现象、根因分析和可立即执行的修复动作。5.1 现象调用任何接口均返回401 Unauthorized错误信息为空或只有{code:INVALID_REQUEST,message:invalid request}原因Authorization请求头中serial_no填写错误。它不是你自己的证书序列号而是微信平台证书wechat_platform_cert.pem的序列号。很多人误用了apiclient_cert.pem的 serial_no。解决打开wechat_platform_cert.pem文件查找serialNumber后面的字符串通常为 40 位十六进制复制粘贴到buildWechatV3Headers()函数中serial_no字段。用命令行快速提取openssl x509 -in certs/wechat_platform_cert.pem -noout -serial | cut -d -f2。5.2 现象/v3/pay/transactions/jsapi返回400 Bad Request错误信息为{code:PARAM_ERROR,message:invalid parameter}且detail.field为空原因notify_url参数未使用 HTTPS 协议或域名未在微信商户平台「产品中心」→「开发配置」中添加白名单。微信 v3 强制要求notify_url为有效 HTTPS 地址。解决检查buildJsapiOrderPayload()中notify_url是否以https://开头登录微信商户平台进入「产品中心」→「开发配置」→「支付授权目录」确保你的域名如https://yourdomain.com/已添加且状态为「已启用」。5.3 现象前端wx.requestPayment调用后立即报错fail: {err_msg:requestPayment:fail invalid sign}原因generateJsapiPaySign()中使用的key不是「APIv3密钥」而是误填了商户号、API 密钥v2 版、或空字符串。该密钥必须在商户平台「API安全」页单独设置且长度为 32 位。解决登录微信商户平台 → 「账户中心」→ 「API安全」→ 「APIv3密钥」点击「设置密钥」生成一个 32 位新密钥复制到generateJsapiPaySign()函数中$apiKey变量。5.4 现象notify_url收到请求但openssl_verify()总是返回0日志显示error:0D0C5006:asn1 encoding routines:ASN1_item_verify:EVP lib原因openssl_x509_read()加载的证书资源无效常见于证书文件损坏、BOM 头存在、或.pem文件中混入了多余空行/注释。微信平台证书必须是纯净的 PEM 格式。解决用vim或notepad以 UTF-8 无 BOM 格式重新保存wechat_platform_cert.pem删除文件开头可能存在的-----BEGIN CERTIFICATE-----之前所有空行和注释运行openssl x509 -in certs/wechat_platform_cert.pem -text -noout验证能否正常输出证书信息。5.5 现象/v3/pay/transactions/out-trade-no/{out_trade_no}查询订单返回404 NOT FOUND但该订单在微信后台「商户平台」中明确存在原因查询接口的 URL 路径中{out_trade_no}是你传入的out_trade_no但微信后台显示的「商户订单号」可能是你系统生成的而接口要求的是「微信支付订单号」transaction_id。out-trade-no接口查的是你自己的订单号不是微信的。解决确认你调用的是/v3/pay/transactions/out-trade-no/{out_trade_no}查你自己的单号还是/v3/pay/transactions/id/{transaction_id}查微信的单号若要查微信单号必须用transaction_id它在支付成功通知的解密体中返回。6. 生产环境加固与自动化验证用 PHPUnit 写一个能跑通的支付闭环测试上线前你不能只靠 Postman 点几下就交付。我习惯用 PHPUnit 写一个端到端的支付闭环测试它会真实走一遍「下单 → 模拟 notify → 查询订单」并在本地 Docker 环境中验证所有证书、签名、解密逻辑。这比人工点十次都可靠。6.1 构建最小可验证测试用例test/PaymentTest.php?php use PHPUnit\Framework\TestCase; class PaymentTest extends TestCase { private $certDir; protected function setUp(): void { $this-certDir __DIR__ . /../certs; // 确保测试环境证书齐全 $this-assertFileExists($this-certDir . /apiclient_cert.pem); $this-assertFileExists($this-certDir . /apiclient_key.pem); $this-assertFileExists($this-certDir . /wechat_platform_cert.pem); } /** * group integration * 测试 JSAPI 下单接口是否能返回 prepay_id */ public function testJsapiOrderReturnsPrepayId() { // 模拟一个测试 openid实际项目中应从测试账号获取 $testOpenId oUpF8uMuAJO_M29Ayb0Zm2qStWYo; // 调用下单函数注意此函数需重构为可注入依赖便于测试 $result requestJsapiOrder($testOpenId); $this-assertArrayHasKey(prepay_id, $result); $this-assertStringStartsWith(prepay_id, $result[package]); $this-assertNotEmpty($result[paySign]); $this-assertEquals(RSA, $result[signType]); } /** * group integration * 测试平台证书能否正确加载并提取公钥 */ public function testPlatformCertLoadAndVerify() { $certPath $this-certDir . /wechat_platform_cert.pem; $certContent file_get_contents($certPath); $certResource openssl_x509_read($certContent); $this-assertIsResource($certResource); $publicKey openssl_pkey_get_public($certResource); $this-assertIsResource($publicKey); // 构造一个假签名消息测试验签基础能力 $fakeMessage post\n/v3/test\n1234567890\nabc\n123; $fakeSignature base64_encode(str_repeat(\x00, 256)); // 占位签名 $result openssl_verify($fakeMessage, base64_decode($fakeSignature), $publicKey, sha256); $this-assertIsInt($result); // 至少不崩溃 } }执行命令vendor/bin/phpunit --group integration test/PaymentTest.php。只要它不报openssl_*函数未定义、证书路径错误、或prepay_id为空就说明你的底层设施已就绪。6.2 本地 Docker 化测试环境docker-compose.yml为彻底隔离环境我用 Docker 启一个 Nginx PHP-FPM 容器挂载证书和代码让测试在接近生产的环境中运行version: 3.8 services: php-test: image: php:8.2-cli volumes: - .:/app - ./certs:/app/certs:ro working_dir: /app command: sh -c composer install vendor/bin/phpunit --group integration test/PaymentTest.php为什么必须 Docker本地 PHP 环境可能启用了openssl.cafile干扰微信证书加载Docker 容器干净、可复现一次通过处处通过。6.3 一份真实的证书与密钥管理清单供上线前核对文件名来源用途是否必须权限要求apiclient_cert.pem微信商户平台「API安全」页下载作为客户端证书用于 HTTPS 双向认证✅ 必须chmod 600apiclient_key.pem同上下载时生成作为客户端私钥用于请求签名✅ 必须chmod 600wechat_platform_cert.pem同上「平台证书」下载提取公钥用于响应验签和通知解密✅ 必须chmod 644apiclient_key.pem.pubopenssl rsa -in apiclient_key.pem -pubout pub.pem仅用于调试生产环境不部署❌ 可选chmod 644从那以后我每次部署新环境都强制走一遍这个清单核对 phpunit测试 curl -v手动下单三连击。不是怕出错是怕出错后花三天去定位到底是证书权限问题还是serial_no填错了。希望帮到你。本文还有配套的精品资源点击获取