簡介本資源是一份面向PHP中高級開發(fā)者的微信支付與退款功能實現(xiàn)方案聚焦電商及在線服務(wù)類網(wǎng)站的支付閉環(huán)需求無需集成微信官方SDK即可快速接入JSAPI支付與原路退款。壓縮包共3個PHP文件總大小僅7KB精簡實用核心為wxpay.class.php封裝統(tǒng)一下單、簽名生成、退款請求等邏輯wxpay.php提供調(diào)用示例notify.php專用于處理支付與退款異步回調(diào)代碼結(jié)構(gòu)清晰、注釋完整便于理解簽名機制、參數(shù)組裝及狀態(tài)校驗等關(guān)鍵環(huán)節(jié)。目前已有1008人學習下載適合希望避開SDK復雜配置、深入掌握微信支付底層交互流程的開發(fā)者可直接復用核心類并結(jié)合業(yè)務(wù)調(diào)整訂單號、密鑰等參數(shù)快速集成到現(xiàn)有項目中。1. 為什么你寫的“PHP微信支付和退款類”上線三天就被商戶投訴資金異常這不是一個講SDK怎么安裝的入門教程。某開發(fā)者在交付一個本地生活SaaS系統(tǒng)時用網(wǎng)上抄來的“通用PHP微信支付類”直接接入微信V3接口結(jié)果退款到賬延遲超2小時、部分訂單重復扣款、回調(diào)驗簽頻繁失敗——不是代碼跑不通而是類的設(shè)計邏輯和微信V3真實業(yè)務(wù)流嚴重脫節(jié)。這個標題里的“類”本質(zhì)是一套可維護、可審計、可灰度、能扛住微信支付網(wǎng)關(guān)抖動與冪等邊界條件的業(yè)務(wù)封裝層不是把curl包一層function就叫“類”。它面向的是需要對接微信支付含JSAPI/H5/小程序、處理原路退款、同步查單、異步通知驗簽、敏感字段加密解密、錯誤重試退避、日志可追溯的中后臺PHP服務(wù)。適合正在用ThinkPHP/Laravel/Swoole或純原生PHP搭建支付中臺、SAAS計費模塊、會員系統(tǒng)且已申請好微信商戶號、配置好APIv3密鑰、開通了退款權(quán)限的工程師。別急著復制粘貼先看清微信支付V3接口和PHP生態(tài)的真實水位線它不接受裸curl、不信任$_POST、不兼容PHP 7.2以下、對時間戳/隨機串/簽名頭格式零容忍。下面帶你從零手寫一個真正能進生產(chǎn)環(huán)境的WechatPayService類。2. 從微信支付V3接口規(guī)范反推類結(jié)構(gòu)為什么必須拆成4個核心組件微信支付V3接口不是“調(diào)個API就行”它是一套強契約、高安全、多狀態(tài)的金融級協(xié)議。直接寫一個WechatPay::pay()方法必然崩盤。我一般會按微信官方文檔的能力域隔離原則把整個類拆成四個不可拆分的組件認證器Auth、請求器Request、響應(yīng)處理器Response、業(yè)務(wù)門面Facade。這不是炫技是為后續(xù)加監(jiān)控、換日志、切流量、做AB測試留出縫。2.1 認證器用APIv3密鑰生成Authorization頭不是拼接字符串微信V3要求每個請求頭帶Authorization: WECHATPAY2-SHA256-RSA2048 ...其值由timestampnonce_strbody三者SHA256哈希后再用商戶私鑰RSA2048簽名。很多人卡在這一步——用openssl_sign()但沒設(shè)OPENSSL_ALGO_SHA256或body沒做JSON標準化空格、換行、鍵序錯亂導致簽名不一致。?php class WechatPayAuth { private $mchId; private $serialNo; private $privateKey; public function __construct(string $mchId, string $serialNo, string $privateKeyPath) { $this-mchId $mchId; $this-serialNo $serialNo; $this-privateKey file_get_contents($privateKeyPath); if (!$this-privateKey) { throw new InvalidArgumentException(Failed to load private key from {$privateKeyPath}); } } public function generateAuthHeader(string $method, string $url, string $body ): array { $timestamp (string)time(); $nonceStr bin2hex(random_bytes(16)); // 必須每次請求新生成 $message $method . \n . parse_url($url, PHP_URL_PATH) . \n . $timestamp . \n . $nonceStr . \n . $body . \n; $signature ; $privateKey openssl_pkey_get_private($this-privateKey); openssl_sign($message, $signature, $privateKey, OPENSSL_ALGO_SHA256); openssl_free_key($privateKey); $authHeader sprintf( WECHATPAY2-SHA256-RSA2048 mchid%s,nonce_str%s,signature%s,timestamp%s,serial_no%s, $this-mchId, $nonceStr, base64_encode($signature), $timestamp, $this-serialNo ); return [ Authorization $authHeader, Wechatpay-Serial $this-serialNo, Wechatpay-Timestamp $timestamp, Wechatpay-Nonce $nonceStr, ]; } }參數(shù)說明$method必須大寫如POST$url必須是完整路徑不含域名如/v3/pay/transactions/jsapi$body必須是未格式化JSON字符串無空格、無換行、鍵名按字典序排列——微信校驗嚴格。$privateKeyPath指向你從微信商戶平臺下載的apiclient_key.pem文件路徑。注意openssl_sign()返回的是二進制簽名必須base64_encode()后填入header。2.2 請求器用cURL而非file_get_contents必須控制超時與重試微信支付網(wǎng)關(guān)有明確SLA支付下單99%請求300ms退款95%1s。但網(wǎng)絡(luò)抖動、DNS解析失敗、連接池耗盡時裸curl會卡死。必須設(shè)置CURLOPT_TIMEOUT_MS非CURLOPT_TIMEOUT并實現(xiàn)指數(shù)退避重試最多2次。?php class WechatPayRequest { private $baseUrl https://api.mch.weixin.qq.com; private $httpClient; public function __construct() { $this-httpClient curl_init(); curl_setopt_array($this-httpClient, [ CURLOPT_RETURNTRANSFER true, CURLOPT_HEADER false, CURLOPT_FOLLOWLOCATION false, CURLOPT_SSL_VERIFYPEER true, // 必須開啟證書校驗 CURLOPT_SSL_VERIFYHOST 2, CURLOPT_CONNECTTIMEOUT_MS 3000, CURLOPT_TIMEOUT_MS 10000, // 總超時10秒微信要求最長15秒 CURLOPT_HTTPHEADER [Content-Type: application/json; charsetutf-8], ]); } public function send(string $method, string $path, array $headers [], string $body ): array { $url $this-baseUrl . $path; $attempts 0; $maxAttempts 2; do { curl_setopt_array($this-httpClient, [ CURLOPT_URL $url, CURLOPT_CUSTOMREQUEST $method, CURLOPT_HTTPHEADER array_merge([Content-Type: application/json; charsetutf-8], $headers), CURLOPT_POSTFIELDS $body, ]); $response curl_exec($this-httpClient); $httpCode curl_getinfo($this-httpClient, CURLINFO_HTTP_CODE); $error curl_error($this-httpClient); if ($response false || $httpCode 0) { if ($attempts $maxAttempts) { usleep((int)pow(2, $attempts) * 100000); // 指數(shù)退避100ms, 200ms continue; } throw new RuntimeException(cURL failed after {$maxAttempts} attempts: {$error}); } $responseBody json_decode($response, true); if (json_last_error() ! JSON_ERROR_NONE) { throw new RuntimeException(Invalid JSON response: . substr($response, 0, 200)); } return [ code $httpCode, body $responseBody, headers $this-parseHeaders(curl_getinfo($this-httpClient, CURLINFO_HEADER_OUT)), ]; } while (false); throw new RuntimeException(Unexpected flow in request); } private function parseHeaders(string $rawHeaders): array { $headers []; foreach (explode(\r\n, trim($rawHeaders)) as $line) { if (strpos($line, :) ! false) { [$key, $value] explode(:, $line, 2); $headers[trim($key)] trim($value); } } return $headers; } }關(guān)鍵點CURLOPT_SSL_VERIFYPEER必須為true微信強制HTTPSCURLOPT_TIMEOUT_MS設(shè)為10000毫秒是平衡成功率與用戶體驗的血淚經(jīng)驗——設(shè)太短丟單設(shè)太長用戶等不及。usleep()退避時間按2^n * 100ms計算這是微信官方推薦的客戶端重試策略。parseHeaders()用于調(diào)試時打印原始請求頭生產(chǎn)環(huán)境可刪。3. 支付與退款的核心業(yè)務(wù)方法如何讓unifiedOrder()和refund()真正冪等微信支付V3的“冪等”不是靠傳out_trade_no就能解決的。它要求同一筆訂單多次調(diào)用下單接口必須返回相同prepay_id同一筆退款多次調(diào)用退款接口必須返回相同refund_id且不重復扣款。這需要你在類里內(nèi)置狀態(tài)機和本地緩存哪怕只是Redis而不是把責任全甩給微信。3.1 下單接口JSAPI支付必須帶openid且notify_url要帶商戶號參數(shù)微信JSAPI支付要求payer.openid字段且notify_url必須是HTTPS、可公網(wǎng)訪問、且不能帶?參數(shù)微信不支持帶query的回調(diào)地址。常見翻車點用$_SERVER[HTTP_REFERER]拼notify_url或把測試域名寫死在代碼里。?php class WechatPayService { private $auth; private $request; private $cache; // PSR-16 cache interface, e.g. Redis public function __construct(WechatPayAuth $auth, WechatPayRequest $request, $cache null) { $this-auth $auth; $this-request $request; $this-cache $cache ?: new ArrayCache(); // fallback } public function unifiedOrder(array $params): array { // 1. 強校驗必填字段 $required [appid, mchid, description, out_trade_no, amount, payer, notify_url]; foreach ($required as $field) { if (!isset($params[$field])) { throw new InvalidArgumentException(Missing required field: {$field}); } } // 2. 構(gòu)建請求體微信要求鍵名小寫、順序固定 $body [ appid $params[appid], mchid $params[mchid], description $params[description], out_trade_no $params[out_trade_no], amount [ total (int)$params[amount][total], currency $params[amount][currency] ?? CNY, ], payer $params[payer], // 必須含 openid notify_url $params[notify_url], // 必須HTTPS且不能帶?參數(shù) ]; // 3. 冪等控制檢查本地是否已存在該out_trade_no的prepay_id $cacheKey wxpay:order: . $params[out_trade_no]; $cached $this-cache-get($cacheKey); if ($cached isset($cached[prepay_id]) $cached[status] success) { return $cached; } // 4. 發(fā)起請求 $headers $this-auth-generateAuthHeader(POST, /v3/pay/transactions/jsapi, json_encode($body)); $result $this-request-send(POST, /v3/pay/transactions/jsapi, $headers, json_encode($body)); if ($result[code] ! 200) { throw new RuntimeException(Wechat pay failed: . json_encode($result[body])); } // 5. 提取prepay_id并緩存TTL 2小時覆蓋微信預支付有效期 $prepayId $result[body][prepay_id] ?? null; if (!$prepayId) { throw new RuntimeException(No prepay_id in response); } $this-cache-set($cacheKey, [ prepay_id $prepayId, status success, created_at time(), ], 7200); return [ prepay_id $prepayId, timestamp (string)time(), nonce_str bin2hex(random_bytes(16)), package prepay_id{$prepayId}, sign_type RSA, ]; } }參數(shù)說明$params[payer]必須是[openid xxx]格式$params[amount]必須是整數(shù)分如100代表1元$params[notify_url]建議用路由生成器動態(tài)拼例如https://yourdomain.com/api/wechat/notify?mchid123456789然后在回調(diào)入口里用$_GET[mchid]區(qū)分多商戶。緩存TTL7200是硬性要求——微信prepay_id2小時過期緩存比它短會導致重復下單。3.2 退款接口必須校驗原訂單狀態(tài)且out_refund_no要全局唯一微信退款要求1原訂單必須是SUCCESS狀態(tài)2退款金額≤原訂單金額3同一out_refund_no只能成功一次。很多人忽略第1條直接調(diào)退款結(jié)果微信返回ORDERNOTEXIST或REFUNDAMOUNTERROR。?php public function refund(array $params): array { // 1. 校驗參數(shù) $required [out_trade_no, out_refund_no, amount]; foreach ($required as $field) { if (!isset($params[$field])) { throw new InvalidArgumentException(Missing refund field: {$field}); } } // 2. 查詢原訂單狀態(tài)微信要求退款前必須確認訂單有效 $orderStatus $this-queryOrder($params[out_trade_no]); if ($orderStatus[status] ! SUCCESS) { throw new InvalidArgumentException(Cannot refund order with status: {$orderStatus[status]}); } // 3. 構(gòu)建退款請求體 $body [ out_trade_no $params[out_trade_no], out_refund_no $params[out_refund_no], amount [ refund (int)$params[amount][refund], total (int)$params[amount][total], currency $params[amount][currency] ?? CNY, ], reason $params[reason] ?? 用戶申請退款, notify_url $params[notify_url] ?? https://yourdomain.com/api/wechat/refund-notify, ]; // 4. 冪等檢查refund_no是否已存在 $refundCacheKey wxpay:refund: . $params[out_refund_no]; $cachedRefund $this-cache-get($refundCacheKey); if ($cachedRefund $cachedRefund[status] success) { return $cachedRefund; } // 5. 調(diào)用微信退款接口 $headers $this-auth-generateAuthHeader(POST, /v3/pay/transactions/out-refunds, json_encode($body)); $result $this-request-send(POST, /v3/pay/transactions/out-refunds, $headers, json_encode($body)); if ($result[code] 200) { $refundId $result[body][refund_id] ?? null; if (!$refundId) { throw new RuntimeException(No refund_id in refund response); } $this-cache-set($refundCacheKey, [ refund_id $refundId, status success, created_at time(), ], 86400); // 退款I(lǐng)D長期有效緩存1天 return [ refund_id $refundId, out_refund_no $params[out_refund_no], status success, ]; } // 微信退款可能返回422業(yè)務(wù)校驗失敗需透出具體錯誤 if ($result[code] 422) { $err $result[body][code] ?? UNKNOWN_ERROR; $msg $result[body][message] ?? Unknown error; throw new RuntimeException(Wechat refund failed ({$err}): {$msg}); } throw new RuntimeException(Wechat refund HTTP error: {$result[code]}); }關(guān)鍵邏輯queryOrder()方法必須先調(diào)用/v3/pay/transactions/id/{transaction_id}或/v3/pay/transactions/out-trade-no/{out_trade_no}查單確保原訂單是SUCCESS。out_refund_no必須由你的系統(tǒng)生成如date(YmdHis) . rand(1000,9999)且全局唯一——微信不接受重復out_refund_no哪怕對應(yīng)不同訂單。緩存TTL86400是因為refund_id永久有效但退款狀態(tài)可能變更如轉(zhuǎn)為ABNORMAL所以實際業(yè)務(wù)中還需定時查單同步狀態(tài)。4. 回調(diào)驗簽與解密為什么90%的“驗簽失敗”都栽在Wechatpay-Serial頭和響應(yīng)體格式上微信所有異步回調(diào)支付成功、退款成功都帶兩個關(guān)鍵頭Wechatpay-Timestamp、Wechatpay-Nonce、Wechatpay-Signature、Wechatpay-Serial。而最常被忽略的是Wechatpay-Serial——它標識本次回調(diào)用的是哪個平臺證書你必須用對應(yīng)的公鑰驗簽。很多人用錯證書或把整個響應(yīng)體當$body傳給驗簽函數(shù)卻忘了微信回調(diào)的$body是原始二進制不是JSON且$message拼接規(guī)則和請求時完全不同。4.1 支付回調(diào)驗簽先取原始body再拼message微信回調(diào)的$_POST為空必須用file_get_contents(php://input)讀原始數(shù)據(jù)。且$message拼接格式為${wechatpay-timestamp}\n${wechatpay-nonce}\n${response-body}\n注意末尾換行。?php public function verifyNotify(string $rawBody, array $headers): bool { // 1. 提取必要header $timestamp $headers[Wechatpay-Timestamp] ?? ; $nonce $headers[Wechatpay-Nonce] ?? ; $signature $headers[Wechatpay-Signature] ?? ; $serial $headers[Wechatpay-Serial] ?? ; if (!$timestamp || !$nonce || !$signature || !$serial) { return false; } // 2. 獲取對應(yīng)序列號的平臺證書需提前從微信下載并緩存 $certPem $this-getPlatformCert($serial); if (!$certPem) { return false; } // 3. 拼接待驗簽字符串注意rawBody是原始二進制不能json_decode $message $timestamp . \n . $nonce . \n . $rawBody . \n; // 4. 驗簽 $pubKey openssl_pkey_get_public($certPem); $ok openssl_verify($message, base64_decode($signature), $pubKey, OPENSSL_ALGO_SHA256); openssl_free_key($pubKey); return $ok 1; } private function getPlatformCert(string $serial): ?string { // 實際項目中這里應(yīng)從Redis或文件緩存讀取證書 // 證書需定期更新微信每3個月輪換建議用定時任務(wù)自動拉取 $certPath /path/to/certs/{$serial}.pem; return file_exists($certPath) ? file_get_contents($certPath) : null; }血淚經(jīng)驗$rawBody必須是原始輸入不能json_decode($rawBody, true)后再拼——微信驗簽用的是原始字節(jié)流。$message末尾的\n是硬性要求漏掉就100%失敗。getPlatformCert()必須支持多證書微信可能同時啟用多個serial且證書要存本地文件不能每次HTTP拉否則高并發(fā)下IO打滿。微信平臺證書有效期90天必須監(jiān)控過期時間并自動刷新。4.2 退款回調(diào)解密用AES-256-GCM不是簡單base64微信退款回調(diào)的resource字段是AES-256-GCM加密的JSON需用$associated_data和$nonce解密。很多人用錯算法如用AES-128-CBC或把$nonce當$iv用或忽略$associated_data。?php public function decryptResource(array $resource, string $apiv3Key): ?array { if (!isset($resource[algorithm], $resource[ciphertext], $resource[nonce], $resource[associated_data])) { return null; } if ($resource[algorithm] ! AEAD_AES_256_GCM) { return null; } $ciphertext base64_decode($resource[ciphertext]); $nonce base64_decode($resource[nonce]); $aad base64_decode($resource[associated_data]); // AES-256-GCM解密 $decrypted openssl_decrypt( $ciphertext, aes-256-gcm, $apiv3Key, OPENSSL_RAW_DATA, $nonce, $aad ); if ($decrypted false) { return null; } $data json_decode($decrypted, true); if (json_last_error() ! JSON_ERROR_NONE) { return null; } return $data; } // 使用示例 // $rawBody file_get_contents(php://input); // $headers getallheaders(); // if ($this-verifyNotify($rawBody, $headers)) { // $notifyData json_decode($rawBody, true); // $decryptData $this-decryptResource($notifyData[resource], $this-apiv3Key); // if ($decryptData $decryptData[refund_status] SUCCESS) { // // 更新本地訂單狀態(tài) // } // }參數(shù)說明$apiv3Key是你在微信商戶平臺設(shè)置的32位APIv3密鑰不是APIv2的key必須嚴格保密。openssl_decrypt()第4個參數(shù)是OPENSSL_RAW_DATA第5個是$nonce第6個是$aad——三者缺一不可。解密失敗時openssl_decrypt()返回false不要直接json_decode()。5. 避坑那些讓線上支付服務(wù)凌晨三點告警的5個真實問題別等線上出事才看日志。以下是我在三個不同項目中踩過的坑每一條都附帶現(xiàn)象、根因和可落地的解決方案。5.1 現(xiàn)象退款成功后用戶收不到錢微信商戶平臺顯示“退款異?！痹蛘{(diào)用退款接口時amount.total傳了字符串100而非整數(shù)100微信后端解析失敗但返回HTTP 200refund_id卻為空。解決在refund()方法開頭強制類型轉(zhuǎn)換$params[amount][refund] (int)$params[amount][refund]; $params[amount][total] (int)$params[amount][total];并在日志中記錄$params[amount]原始值便于排查。5.2 現(xiàn)象支付回調(diào)驗簽通過但$rawBody解析出的resource字段為空原因Nginx配置了client_max_body_size 1M而微信回調(diào)體可能超1MB尤其含大量商品信息時導致body被截斷。解決在Nginx配置中增加location /api/wechat/notify { client_max_body_size 5M; fastcgi_buffer_size 128k; fastcgi_buffers 4 256k; }并用strlen($rawBody)校驗長度小于100字節(jié)即告警。5.3 現(xiàn)象同一out_trade_no多次調(diào)用unifiedOrder()返回不同prepay_id原因緩存使用了memcached但未設(shè)置serialize選項導致ArrayCachefallback生效而ArrayCache不支持跨進程共享。解決強制使用Redis緩存并在構(gòu)造函數(shù)中校驗if (!$cache instanceof \Psr\SimpleCache\CacheInterface) { throw new InvalidArgumentException(Cache must implement PSR-16); }5.4 現(xiàn)象WechatPayAuth::generateAuthHeader()偶爾生成重復nonce_str原因bin2hex(random_bytes(16))在某些PHP版本如7.3以下的random_bytes()可能返回弱熵導致碰撞。解決改用更健壯的生成方式$nonceStr bin2hex(openssl_random_pseudo_bytes(16)); if (!$nonceStr) { $nonceStr bin2hex(random_bytes(16)); }5.5 現(xiàn)象退款回調(diào)解密后$decryptData[refund_status]始終為PROCESSING原因微信退款是異步流程PROCESSING表示正在處理需等待5-30分鐘但業(yè)務(wù)代碼誤以為失敗觸發(fā)重試導致微信重復退款。解決在回調(diào)處理中對PROCESSING狀態(tài)不做任何DB更新僅記錄日志并啟動一個5分鐘后的延遲任務(wù)查單if ($decryptData[refund_status] PROCESSING) { // 推送延遲任務(wù)到隊列5分鐘后執(zhí)行 queryRefund($out_refund_no) $this-delayQueue-push(check_refund_status, [ out_refund_no $out_refund_no, retry_count 0, ], 300); // 5分鐘 }6. 進階技巧用phpstan和psalm靜態(tài)分析守住支付類的類型安全紅線支付類一旦出錯就是資金事故不能只靠單元測試。我堅持在CI中加入靜態(tài)分析堵住90%的低級錯誤。比如unifiedOrder()的$params[amount][total]必須是int但PHP默認是stringjson_encode()后微信會拒收。6.1 用PHPStan定義嚴格類型契約在phpstan.neon中添加parameters: level: 8 paths: - src/WechatPayService.php typeToStrictTypes: int: [int, integer] string: [string] checkAlwaysTrueCheckTypeFunctionCall: true然后在類方法注釋中寫明/** * param array{ * appid: string, * mchid: string, * description: string, * out_trade_no: string, * amount: array{total: int, currency?: string}, * payer: array{openid: string}, * notify_url: string * } $params * return array{prepay_id: string, timestamp: string, nonce_str: string, package: string, sign_type: string} */ public function unifiedOrder(array $params): array運行vendor/bin/phpstan analyse它會立刻報錯Parameter #1 $params of method WechatPayService::unifiedOrder() expects array{amount: array{total: int, ...}, ...}, parent type array given.逼你把$params[amount][total] (int)$_POST[total]寫進代碼而不是靠“應(yīng)該沒問題”的僥幸。6.2 用Psalm檢測數(shù)組鍵缺失風險Psalm能發(fā)現(xiàn)$params[payer][openid]可能不存在的問題。在psalm.xml中projectFiles directory namesrc / ignoreFiles directory namevendor / /ignoreFiles /projectFiles并在方法上加/** * psalm-param array{payer: array{openid: string}} $params */當有人傳[payer []]時Psalm直接標紅“Missing keyopenidin array”。6.3 給關(guān)鍵方法加throws文檔讓IDE自動提示異常鏈/** * throws InvalidArgumentException 當參數(shù)缺失或格式錯誤 * throws RuntimeException 當微信接口返回非200或JSON解析失敗 * throws RuntimeException 當驗簽失敗或解密失敗 */ public function verifyNotify(string $rawBody, array $headers): bool這樣在調(diào)用處PHPStorm會顯示所有可能拋出的異常提醒你try-catch而不是讓Exception一路冒泡到頂層500。最后說一句我寫這個類的第7版時把WechatPayService拆成了WechatPayV3Client純HTTP、WechatPayDomain業(yè)務(wù)規(guī)則、WechatPayGateway適配器因為某次微信突然升級了證書格式只改了一個適配器就全量切流。支付類不是越“全能”越好而是越“可替換”越穩(wěn)。希望幫到你。本文還有配套的精品資源點擊獲取