使用 PHP SDK

更新时间:2025.05.29

在本教程中,你将简要了解微信支付的 PHP SDK。在学习过程中,你将

  • 掌握如何安装 PHP SDK

  • 了解请求微信支付需要哪些密钥和证书

  • 了解如何使用 PHP SDK 请求微信支付

环境要求

  • Guzzle 7.0,PHP >= 7.2.5。

  • Guzzle 6.5,PHP >= 7.1.2

我们推荐使用目前处于 Active Support 阶段的 PHP 8 和 Guzzle 7。

安装

使用 Composer 安装最新版本的 SDK:

1composer require wechatpay/wechatpay

你可以在 GitHub 找到 PHP SDK 的源代码、使用说明和最新版本信息。

必需的证书和密钥

运行 SDK 必需以下的证书和密钥:

由于 PHP-FPM 进程模型限制,PHP SDK 不支持自动获取和更新微信支付平台证书。你可以使用 SDK 自带的工具下载微信支付平台证书。

1composerexec CertificateDownloader.php -- -k ${apiV3key} -m ${mchId} -f ${mchPrivateKeyFilePath} -s ${mchSerialNo} -o ${outputFilePath}

注意:

如果使用上述命令下载平台证书报错:{"code": "RESOURCE_NOT_EXISTS","message": "无可用的平台证书,请在商户平台-API安全申请使用微信支付公钥。"},即表示商户仅能使用微信支付公钥,可参考下方发起请求中的使用微信支付公钥初始化示例

发起请求

以 Native 支付为例,向微信支付发起你的第一个请求。

使用微信支付平台证书初始化
使用微信支付公钥初始化
1<?php
2  
3require_once('vendor/autoload.php');
4
5use WeChatPay\Builder;
6use WeChatPay\Crypto\Rsa;
7
8// 设置参数
9
10// 商户号
11$merchantId = '190000****';
12
13// 从本地文件中加载「商户API私钥」,「商户API私钥」会用来生成请求的签名
14$merchantPrivateKeyFilePath = 'file:///path/to/merchant/apiclient_key.pem';
15$merchantPrivateKeyInstance = Rsa::from($merchantPrivateKeyFilePath, Rsa::KEY_TYPE_PRIVATE);
16
17// 「商户API证书」的「证书序列号」
18$merchantCertificateSerial = '3775B6A45ACD588826D15E583A95F5DD********';
19
20//从本地文件中加载「微信支付公钥」,用来验证微信支付应答的签名
21$platformPublicKeyFilePath = 'file:///path/to/wechatpay/publickey.pem';
22$twoPlatformPublicKeyInstance = Rsa::from($platformPublicKeyFilePath, Rsa::KEY_TYPE_PUBLIC);
23
24// 「微信支付公钥」的「微信支付公钥ID」
25// 需要在 商户平台 -> 账户中心 -> API安全 查询
26$platformPublicKeyId = 'PUB_KEY_ID_01142321349124100000000000********';
27
28// 构造一个 APIv3 客户端实例
29$instance = Builder::factory([
30    'mchid'      => $merchantId,
31    'serial'     => $merchantCertificateSerial,
32    'privateKey' => $merchantPrivateKeyInstance,
33    'certs'      => [
34        $platformPublicKeyId => $twoPlatformPublicKeyInstance,
35    ],
36]);
37
38// 以 Native 支付为例,发送请求
39$resp = $instance -> chain('v3/pay/transactions/native') -> post(['json' => [
40        'mchid' => '1900006XXX',
41        'out_trade_no' => 'native12177525012014070332333',
42        'appid' => 'wxdace645e0bc2cXXX',
43        'description' => 'Image形象店-深圳腾大-QQ公仔',
44        'notify_url' => 'https://weixin.qq.com/',
45        'amount' => [
46            'total' => 1,
47            'currency' => 'CNY'
48        ],
49    ],
50    //在http请求增加一个Wechatpay-Serial请求头,具体作用可参考:https://pay.weixin.qq.com/doc/v3/merchant/4012154180#5.2-%E5%88%87%E6%8D%A2%E9%AA%8C%E7%AD%BE%E5%92%8C%E5%AE%9E%E7%8E%B0%E5%9B%9E%E8%B0%83%E5%85%BC%E5%AE%B9
51    'headers' => [
52        'Wechatpay-Serial' => '134912410000000000000xxxxxxx',
53    ],
54]);
55
56print_r(json_decode((string) $resp->getBody(), true));
57//当程序进入「异常捕获」逻辑,输出形如:
58{
59    "code": "RESOURCE_NOT_EXISTS",
60    "message": "无可用的平台证书,请在商户平台-API安全申请使用微信支付公钥。"
61}
62//即表示商户仅能使用微信支付公钥初始化模式

联系 SDK 团队获取帮助

接下来阅读

通过这个快速介绍,你已经安装了 PHP SDK 并学习了一些基础知识。接下来,你可以阅读具体的产品文档,学习如何接入微信支付。

 

反馈
咨询
目录
置顶