PHP微信支付与退款类封装实战：APIv3签名、回调验签与踩坑指南

简介面向PHP开发者的微信支付与退款功能实现资源聚焦电商及在线服务站点常见的支付场景采用JSAPI方式完成公众号内支付并覆盖订单退款全流程。相比集成官方SDK本实现以轻量PHP类库方式简化调用适合需要快速接入支付能力、又希望保留灵活定制空间的中级开发者。资源包共3个PHP文件大小仅7KB结构紧凑包含支付主类、公共配置与异步通知处理脚本便于阅读和二次修改。核心示例代码完整演示了统一下单生成预支付订单、基于商户密钥生成JSAPI签名、前端JSSDK触发支付以及退款申请、退款状态查询与回调通知解析等关键环节并附有参数拼接、加密与防重处理思路。对于初次接触微信支付或需要参考退款实现细节的开发者这套代码能直接降低联调门槛。目前已有1008人学习属于实用型入门参考。整体保持与微信支付官方文档同步更新即可快速落地到项目中。1. PHP微信支付和退款类一次封装告别散落在业务代码里的支付逻辑很多项目做到一半微信支付总是同一个剧情业务方觉得“就一个收款和退款很简单”等你真正对接才发现签名、证书、回调验签、退款状态同步每个环节都像一个黑匣子不翻一次车根本看不到边界。PHP对接“微信支付接口”还有个历史包袱网上大量代码还停留在APIv2的MD5签名时代直接用到新接口上只会得到一串看不懂的错误码。我通常的做法是把微信支付和退款封装成一个独立的PHP类统一下单、回调处理、申请退款、结果查询全部收进类里业务层只调方法、传参数。这套“PHP微信支付和退款类”的设计既让新项目避开重复踩坑也让老项目以后换支付渠道时不伤筋动骨。适合小程序后端、电商系统、外包项目里那些想把支付模块一次做干净的PHP工程师。2. 微信支付APIv3对接核心证书、签名与PHP客户端的选型逻辑2.1 APIv3与APIv2为什么新项目必须选APIv3微信支付开放平台从2019年前后开始主推APIv3和旧的APIv2相比最核心的变化有三点第一请求和响应格式从XML变成了JSON告别了那一堆需要转义、解析还容易踩坑的XML节点第二签名方式从MD5升级为SHA256withRSA商户侧用商户私钥签名微信侧用平台证书验签双向验签让伪造回调的成本高了一大截第三回调通知用AES-256-GCM加密业务数据在传输过程中全程加密即使回调地址被第三方拿到也解不出明文。APIv2现在虽然还能用但微信官方对新能力、新场景的支持基本都转到了APIv3上。像小程序支付的“用户态签名”、商家转账、分账这些能力APIv2压根没有对应接口。新项目如果再按APIv2去做等于是把项目绑在一条不断缩水的船票上。这套PHP微信支付和退款类我们统一基于APIv3实现覆盖统一下单、支付回调、申请退款、退款查询四个核心接口代码结构上也为后续新增商家转账、分账预留扩展位。2.2 商户证书、API密钥与平台证书三个容易搞混的配置项初次对接APIv3最容易在证书环节卡住。三个配置项看下面这张表分清谁负责签名、谁负责解密、谁负责验签。配置项从哪来作用常见误解商户API证书商户私钥微信商户平台下载含商户号和证书序列号商户请求时用私钥做SHA256withRSA签名以为要上传给微信验证实际私钥要放在自己的服务器里绝不能泄漏APIv3密钥API Key商户平台手动设置32字节解密回调通知里的敏感数据比如out_trade_no和APIv2的32位API Key混淆两者用途完全不同微信支付平台证书从微信官方下载或通过接口自动更新验证微信响应和回调通知的签名以为平台证书和商户证书是一对平台证书定期轮换需要自动处理这三个配置项在PHP类里建议用构造参数注入不硬编码到类内部。这样测试环境和生产环境切换时只改配置文件不动业务代码。私钥一般以PEM文件形式提供从商户平台下载的apiclient_key.pem就是标准PEMPHP的openssl扩展可直接读取。注意生产环境不要把商户私钥放到web根目录下建议放在独立配置目录并通过环境变量把文件路径注入到配置对象里。2.3 用PHP实现APIv3的请求签名Authorization头组装APIv3最常翻车的点是Authorization头的组装。微信要求每个请求头都带上WECHATPAY2-SHA256-RSA2048认证信息而待签名串由请求方法、请求路径、时间戳、随机串、请求体五个元素按\n拼接而成。下面这段签名方法是整个支付和退款类的基础所有请求都走它。?php class WxPayV3Signer { private $merchantId; // 商户号 private $certSn; // 商户API证书序列号 private $privateKey; // 商户私钥对象 public function __construct(string $merchantId, string $certSn, string $privateKeyPem) { $this-merchantId $merchantId; $this-certSn $certSn; $this-privateKey openssl_pkey_get_private($privateKeyPem); if ($this-privateKey false) { throw new \RuntimeException(商户私钥读取失败, 请检查PEM文件); } } /** * 生成Authorization请求头 * param string $method GET / POST 等 * param string $urlPath 请求路径, 例如 /v3/pay/transactions/jsapi * param string $body 请求体, GET请求传空字符串 */ public function authHeader(string $method, string $urlPath, string $body ): array { $timestamp time(); $nonce bin2hex(random_bytes(16)); // 待签名串: 方法 路径 时间戳 随机串 请求体, 每段用换行符分隔 $message $method . \n . $urlPath . \n . $timestamp . \n . $nonce . \n . $body . \n; openssl_sign($message, $signature, $this-privateKey, OPENSSL_ALGO_SHA256); $auth sprintf( WECHATPAY2-SHA256-RSA2048 mchid%s,nonce_str%s,signature%s,timestamp%d,serial_no%s, $this-merchantId, $nonce, base64_encode($signature), $timestamp, $this-certSn ); return [Authorization $auth]; } }这段代码有三个要点。第一待签名串的换行符是\n顺序是method、urlPath、timestamp、nonce、body少一个或顺序换一下签名就通不过。第二openssl_sign用的是OPENSSL_ALGO_SHA256对应微信文档说的SHA256withRSA不要在这里自作聪明换成别的算法。第三签名结果要做base64编码再放进Authorization头。随机串用random_bytes而不是uniqid()因为随机串的可预测程度直接影响签名安全在支付场景里这是底线。2.4 请求发送与响应验签只签名不回验等于白做签名只是前半段后半段是验签。创建订单这类接口的响应头带Wechatpay-Timestamp、Wechatpay-Nonce、Wechatpay-Signature三个字段响应体是JSON。拿到后先验签、再解析。如果验签不过响应内容就要视为伪造或篡改不能进入业务处理。public function getWithVerify(string $urlPath): array { $headers $this-authHeader(GET, $urlPath, ); $response $this-request(GET, https://api.mch.weixin.qq.com . $urlPath, $headers); // 从响应头里取出验签三件套 $timestamp $response[headers][Wechatpay-Timestamp]; $nonce $response[headers][Wechatpay-Nonce]; $signature $response[headers][Wechatpay-Signature]; $body $response[body]; // 验签消息体是时间戳 换行 随机串 换行 响应体 换行 $message $timestamp . \n . $nonce . \n . $body . \n; $verify openssl_verify( $message, base64_decode($signature), $this-platformCert, // 微信支付平台证书公钥 OPENSSL_ALGO_SHA256 ); if ($verify ! 1) { throw new \RuntimeException(微信响应验签失败, 可能遭遇中间人攻击或平台证书过期); } return json_decode($body, true); }注意这里的验签对象是timestamp \n nonce \n body \n和请求签名的拼接方式不完全一样别把两套流程的字符串结构混着用。平台证书必须使用微信官方下发的“微信支付平台证书”不能用商户证书验签否则签名永远验不过。2.5 官方SDK与自研封装怎么选最合适微信官方PHP SDK能在微信支付开发者文档里找到覆盖了APIv3的基础请求、验签、解密对刚上手的项目来说确实省事。但官方SDK把HTTP发送也封装在内部换不上公司统一的HTTP客户端或链路追踪。我的做法是参考它的核心流程自己封装一个薄的WxPayClient只做签名、验签、解密三件事HTTP传输交给项目里已有的Guzzle或统一HTTP封装。这样支付类很容易单测——传一个请求对象进去直接断言签名头和返回解析是否正确不依赖真实网络环境。3. PHP支付类怎么设计从统一下单到回调处理的完整闭环3.1 类的拓扑配置注入、请求上下文与业务方法分离把支付和退款塞进同一个类写起来方便但类会迅速膨胀到上千行。我一般拆成三个类WxPayConfig只保存配置WxPayClient负责签名和HTTP发送WxPayService面向业务提供createOrder、refund、handleNotify等方法。业务层只依赖WxPayService微信支付的细节全部隔离在Service内部。硬编码商户号、私钥路径之类的坚决不做WxPayConfig从环境变量或配置文件读取保证本地、测试、生产三套环境共用一套代码。?php class WxPayConfig { public $appId; // 小程序/公众号的AppId public $mchId; // 商户号 public $certSn; // 商户证书序列号 public $privateKeyPem; // 商户私钥PEM文件路径 public $platformCertPem; // 平台证书PEM文件路径 public $apiV3Key; // APIv3密钥 public $notifyUrl; // 回调地址 public function __construct(array $config) { foreach ($config as $key $value) { $this-$key $value; } } }配置文件里放什么决定了这套类好不好切换环境。我习惯在.env里定义WX_APP_ID、WX_MCH_ID、WX_CERT_SN、WX_PRIVATE_KEY_PATH、WX_PLATFORM_CERT_PATH、WX_API_V3_KEY、WX_NOTIFY_URL程序启动时读取并构造WxPayConfig。这样新同事接手项目时不用翻代码就知道要配哪几项。3.2 统一下单从订单参数到prepay_id小程序支付走JSAPI下单接口是POST /v3/pay/transactions/jsapi核心参数包括appid、mchid、description、out_trade_no、notify_url、amount.total、payer.openid。这里的total单位是分不是元传1元时要写100out_trade_no是商户侧生成的订单号同一个商户号下不能重复。发起下单后微信返回prepay_id这个id是下一步拉起小程序支付的关键凭证。public function createOrder(string $openid, string $outTradeNo, int $totalFee, string $desc): array { $path /v3/pay/transactions/jsapi; $body [ appid $this-config-appId, mchid $this-config-mchId, description $desc, out_trade_no $outTradeNo, notify_url $this-config-notifyUrl, amount [total $totalFee, currency CNY], payer [openid $openid], ]; $result $this-client-postJson($path, $body); return $result; // 返回结果里包含 prepay_id }两个新手容易忽略的点一是notify_url必须是公网可访问的HTTPS地址不能被重定向否则微信回调会失败二是description不要太长微信会校验字符长度超长会返回PARAM_ERROR。下单成功后prepay_id的有效期是两小时过期后要重新下单。3.3 拉起小程序支付prepay_id之外的二次签名createOrder返回的prepay_id不能直接给前端用。小程序端调wx.requestPayment时需要再组装一个支付参数包appId、timeStamp、nonceStr、package值为prepay_idxxxx、signType然后用商户私钥对这个参数包签名。很多新手在第二步踩坑以为prepay_id可以直接用结果小程序报“支付验证签名失败”。public function buildPayParams(string $prepayId): array { $timestamp (string)time(); $nonceStr bin2hex(random_bytes(16)); $package prepay_id . $prepayId; // 签名串顺序: appId, timeStamp, nonceStr, package, 每个值后带换行 $message $this-config-appId . \n . $timestamp . \n . $nonceStr . \n . $package . \n; openssl_sign($message, $signature, $this-client-getPrivateKey(), OPENSSL_ALGO_SHA256); return [ appId $this-config-appId, timeStamp $timestamp, nonceStr $nonceStr, package $package, signType RSA, paySign base64_encode($signature), ]; }这里的签名串和微信APIv3标准请求签名串不是一回事它是专门用于支付参数包的格式。注意timeStamp在这里必须是字符串类型PHP如果直接输出成数字在小程序端做类型校验时会过不去。paySign要base64编码后返回前端拿到的值不能有多余换行或空格。3.4 支付结果回调验签、解密与更新订单的正确顺序支付结果回调是整个链路里最容易出事的环节。微信在用户支付成功后会把加密的通知POST到notify_url而且同一笔支付会重发多次直到业务端返回SUCCESS。处理顺序必须是先验签再解密再更新订单最后返回成功应答。public function handleNotify(string $headers, string $body): string { // 1. 从headers里取 Wechatpay-Signature 等验签字段 if (!$this-client-verifyResponseHeaders($headers, $body)) { return {code:FAIL,message:验签失败}; } // 2. 解密 resource 节点 $notify json_decode($body, true); $resource $notify[resource]; $decrypted $this-client-decryptAes256Gcm( $resource[ciphertext], $resource[nonce], $resource[associated_data] ); $data json_decode($decrypted, true); // 3. 先判断订单状态, 已支付就直接返回成功, 避免重复处理 $outTradeNo $data[out_trade_no]; $transactionId $data[transaction_id]; $tradeState $data[trade_state]; if ($tradeState SUCCESS $this-orderRepository-isPaid($outTradeNo) false) { $this-orderRepository-markPaid($outTradeNo, $transactionId); } // 4. 返回成功应答 return {code:SUCCESS,message:成功}; }解密方法注意一个细节微信回调里的ciphertext是Base64字符串密文后面还带了16字节的认证标签。用PHP的openssl_decrypt时要先把Base64解码从密文末尾截出认证标签再把剩余部分交给aes-256-gcm解密。APIv3密钥在解密前要hex2bin转成二进制直接用字符串密钥会解出一堆乱码。4. 退款类封装实战申请、查询与状态同步的落地写法4.1 申请退款参数、幂等性与金额单位退款接口路径是POST /v3/refund/domestic/refunds核心参数有三个原订单号out_trade_no、商户退款单号out_refund_no、退款金额amount.refund另外还必须带amount.total和amount.currency。血泪教训是refund是本次要退的金额total是原订单实付金额两个都以分为单位。部分退款时refund必须小于等于total大于会直接报PARAM_ERROR。public function refund(string $outTradeNo, int $refundAmount, int $totalAmount, string $reason ): array { // 退款单号由程序生成, 带日期前缀方便对账; 同一单号重复请求, 微信只处理一次 $outRefundNo date(YmdHis) . bin2hex(random_bytes(3)); $path /v3/refund/domestic/refunds; $body [ out_trade_no $outTradeNo, out_refund_no $outRefundNo, amount [ refund $refundAmount, // 本次退多少 total $totalAmount, // 原订单实付金额 currency CNY, ], reason $reason, ]; return $this-client-postJson($path, $body); }out_refund_no我建议由程序自动生成而不是让调用方传因为退款接口靠它做幂等。调用方一旦在重试时换了一个单号就会产生两笔退款。退款金额和订单金额的差额如果是因为优惠券、运费之类的平台补贴微信在退款时会按资金比例从各方扣除这个不做额外处理但要在对账单里能看清。4.2 退款结果确认退款回调与主动查询双保险退款接口返回后状态是PROCESSING真正成功要等微信内部处理。这时候有两条确认路径一是退款结果回调微信在退款成功或失败后主动通知二是主动查询GET /v3/refund/domestic/refunds/{out_refund_no}。我的习惯是两条都做回调为主查询为辅。回调的及时性好但回调地址可能因为网络抖动没收到或服务器在回调期间重启了。第二天对账时靠主动查询把漏掉的补平。public function queryRefund(string $outRefundNo): array { $path /v3/refund/domestic/refunds/ . $outRefundNo; $response $this-client-getJson($path); $status $response[status]; // SUCCESS / CLOSED / PROCESSING / ABNORMAL if ($status SUCCESS) { $this-refundRepository-markRefunded($outRefundNo, $response[refund_id]); } return $response; }查询接口返回的status有四个取值SUCCESS退款成功、CLOSED退款关闭、PROCESSING退款处理中、ABNORMAL退款异常。注意不要再把PROCESSING当成最终态也不要只查一次就放弃。我一般用定时任务对状态为PROCESSING的退款单做轮询超过24小时还是PROCESSING的转人工介入。退款回调的结构和支付回调类似resource里解密后能看到out_refund_no、refund_status、refund_id等字段。处理时同样要先判状态refund_status为SUCCESS才更新退款记录CHANGE表示退款异常要触发告警。退款回调的应答格式和支付回调相同成功返回{code:SUCCESS,message:成功}。4.3 退款状态机别让业务层散落一堆if判断如果把退款状态判断散落在业务代码里后面加一个“原路退回失败再退余额”的需求时你会发现自己开始复制粘贴。我在类里维护一组静态常量业务层只认这组常量里的值class RefundStatus { const PROCESSING PROCESSING; // 退款处理中 const SUCCESS SUCCESS; // 退款成功 const CLOSED CLOSED; // 退款关闭 const ABNORMAL ABNORMAL; // 退款异常 const NOT_EXISTS NOT_EXISTS; // 退款单不存在 }业务层调用退款后只记住out_refund_no后续所有对退款状态的判断都通过queryRefund()结果驱动。状态为SUCCESS才允许给用户发退款到账通知ABNORMAL时转人工审核。这样可以避免在控制器里写“if status SUCCESS 改数据库”这种和微信字段耦合过深的代码。退款单号在业务表里建议加唯一索引防止同一笔订单被人为发起两次全额退款。5. 微信支付与退款对接常见问题5个必须提前知道的踩坑点5.1 小程序端提示“用户态签名signature错误”现象小程序调wx.requestPayment或虚拟支付能力时返回用户态签名signature错误但服务端日志显示统一下单接口正常返回了prepay_id。原因这个signature不是服务端下单接口返回的paySign而是小程序端通过wx.login拿到code后再用会话密钥基于业务参数生成的另一个签名。服务端如果把下单返回的paySign直接当成用户态签名传给小程序两边对不上。解决确认报错发生在“拉起支付”阶段还是“业务后端校验”阶段。如果是用户态签名场景需要额外用session_key配合业务参数生成签名放在独立接口里不要和统一下单混在一起。业务端收到signature后做一次验签再放行。5.2 回调验签永远失败平台证书和商户证书混用现象自己的接口测试一切正常一部署到线上支付回调的验签几乎全部失败日志里一片verify return code ! 1。原因验签时用的是商户证书而不是微信支付平台证书。这两个证书一个是商户的一个是微信的公钥完全对不上。另一个常见诱因是平台证书长期未更新微信定期轮换平台证书后本地还保留旧证书。解决验签前先确认加载的是wechatpay开头的平台证书不是apiclient开头的商户证书。平台证书的自动更新要做成定时任务每天检查一次微信更新后自动拉取新证书并缓存。证书缓存可以用文件也可以用Redis但必须保证更新后旧证书有一段时间的过渡期避免和微信侧不同步。5.3 退款金额差了100倍单位“分”与“元”的转换现象订单金额10元退款时传了10结果微信报错或退款成功后只退了0.1元。原因微信APIv3的金额单位全程是“分”10元要写成1000。前端习惯显示元后端如果直接把前端传的金额透传给微信就会差100倍。解决在支付类里统一一个金额转换方法所有对外接口接收元、内部存分为单位杜绝在业务层到处写*100。public function moneyToFen($yuan): int { // 用字符串运算或round, 避免浮点精度问题 return (int) round((float)$yuan * 100); }浮点运算里0.1*100可能变成10.000000000000002直接截断会出问题。金额字段在数据库里建议用decimal(10,2)存储PHP侧用字符串类型接收避免float精度丢失。5.4 并发回调导致订单被覆盖缺少幂等判断现象同一笔订单在高峰期收到两次回调第一次处理成功第二次又把订单状态改成了“待支付”或者产生了两条补单记录。原因微信同一笔支付会重发通知直到收到SUCCESS应答。如果业务处理逻辑没有先判断当前订单状态就会重复走一遍更新流程。集群部署时两次回调可能同时落在不同实例上两个进程同时去改订单状态后写覆盖先写。解决回调里第一步查订单状态已支付则直接返回SUCCESS。更新订单用带条件的SQL比如UPDATE orders SET statuspaid WHERE order_no? AND statuspending影响行数为0就不重复处理。退款同理退款单状态为SUCCESS后重复回调直接忽略。5.5 测试环境没有正式沙箱用模拟支付开关补位现象新人在没有真实商户号的环境下想测支付回调结果只能对着报错看流程根本走不通。原因APIv3不像某些开放平台提供全功能沙箱不真实支付就不会有回调本地联调环境很难完整跑通。解决在类里加一个mock开关测试环境开启后统一下单直接返回预置的prepay_id并允许手动触发一条模拟回调请求到notify_url。这样支付流程能在持续集成里跑通不用依赖外部环境。上线前再用真实商户号做一次全链路验收重点核对回调验签和退款到账。6. 把支付类变成项目基石的3个进阶技巧日志脱敏、模拟支付与配置隔离支付类上线后真正要补的不是新功能而是三个容易被忽略的工程习惯。第一个是日志脱敏。支付和退款相关的报错日志最容易泄漏敏感字段。我习惯在WxPayClient的日志入口统一过滤掉Authorization头、请求体里的openid、回调里的ciphertext只保留商户订单号、退款单号、金额、返回的状态码和err_code。这样排查问题时日志是干净的也不会因为日志泄露触发安全整改。第二个是模拟支付开关的日常化使用。前面避坑里提到mock模式实际落地时我会把它做成一个独立配置而不是藏在代码里的if判断。持续集成测试只跑mock模式每次发布前自动验证下单、回调、退款三个核心方法能正常返回。这样即使微信侧接口升级只要mock模式通过业务代码大概率没被破坏。第三个是配置隔离和证书轮换的自动化。WxPayConfig从环境变量读取商户私钥路径、平台证书路径、APIv3密钥都走配置中心不写死在代码里。平台证书轮换这件事我吃过亏线上突然验签失败查了半天发现是证书过期。后来加了每天一次的定时任务主动调用微信的证书下载接口并更新缓存再自动重载WxPayClient里的平台证书。这次之后验签失败再没出现过。支付和退款类写起来不难难的是把它当成一个长期演进的模块来维护。每次微信文档更新我都会先看变更日志再对着自己的类检查一遍签名和回调处理逻辑有没有受影响。这个习惯帮我避免了好几次线上翻车。如果你正在做PHP微信支付和退款类建议先把签名、验签、幂等这三件事做扎实再考虑功能 completeness。希望帮到你。本文还有配套的精品资源点击获取