---
url: "https://pay.weixin.qq.com/doc/v3/partner/4012083112.md"
title: "使用 PHP SDK"
doc_id: 4012083112
---

>更新时间：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](https://www.php.net/supported-versions.php) 阶段的 PHP 8 和 Guzzle 7。

## 安装

使用 [Composer](https://getcomposer.org/) 安装最新版本的 SDK：

```
composer require wechatpay/wechatpay
```

你可以在 GitHub 找到 [PHP SDK](https://github.com/wechatpay-apiv3/wechatpay-php) 的源代码、使用说明和最新版本信息。

## 必需的证书和密钥

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

- [商户 API 私钥](https://pay.weixin.qq.com/doc/v3/merchant/4013053053.md#%E5%A6%82%E4%BD%95%E8%8E%B7%E5%8F%96%E5%95%86%E6%88%B7API%E8%AF%81%E4%B9%A6%E7%A7%81%E9%92%A5%EF%BC%9F)

- [商户 API 证书](https://pay.weixin.qq.com/doc/v3/merchant/4013053053.md)的证书序列号

- [APIv3 密钥](https://pay.weixin.qq.com/doc/v3/merchant/4013053267.md)

- [微信支付平台证书](https://pay.weixin.qq.com/doc/v3/merchant/4012068814.md#4.-%E5%A6%82%E4%BD%95%E8%8E%B7%E5%8F%96%E5%B9%B3%E5%8F%B0%E8%AF%81%E4%B9%A6)或[微信支付公钥](https://pay.weixin.qq.com/doc/v3/merchant/4012153196.md)


由于 [PHP-FPM](https://www.php.net/manual/zh/install.fpm.php) 进程模型限制，PHP SDK 不支持自动获取和更新微信支付平台证书。你可以使用 SDK 自带的[工具](https://github.com/wechatpay-apiv3/wechatpay-php/blob/main/bin/README.md)下载微信支付平台证书。

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

注意：

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

## 发起请求

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

使用微信支付平台证书初始化

使用微信支付公钥初始化```
<?php

require_once('vendor/autoload.php');

use WeChatPay\Builder;
use WeChatPay\Crypto\Rsa;
use WeChatPay\Util\PemUtil;

// 设置参数

// 商户号
$merchantId = '190000****';

// 从本地文件中加载「商户API私钥」，「商户API私钥」会用来生成请求的签名
$merchantPrivateKeyFilePath = 'file:///path/to/merchant/apiclient_key.pem';
$merchantPrivateKeyInstance = Rsa::from($merchantPrivateKeyFilePath, Rsa::KEY_TYPE_PRIVATE);

// 「商户API证书」的「证书序列号」
$merchantCertificateSerial = '3775B6A45ACD588826D15E583A95F5DD********';

// 从本地文件中加载「微信支付平台证书」(可使用证书下载工具得到），用来验证微信支付应答的签名
$platformCertificateFilePath = 'file:///path/to/wechatpay/cert.pem';
$platformPublicKeyInstance = Rsa::from($platformCertificateFilePath, Rsa::KEY_TYPE_PUBLIC);

// 从「微信支付平台证书」中获取「证书序列号」
$platformCertificateSerial = PemUtil::parseCertificateSerialNo($platformCertificateFilePath);

// 构造一个 APIv3 客户端实例
$instance = Builder::factory([
    'mchid' => $merchantId,
    'serial' => $merchantCertificateSerial,
    'privateKey' => $merchantPrivateKeyInstance,
    'certs' => [
        $platformCertificateSerial => $platformPublicKeyInstance,
    ],
]);

// 以 Native 支付为例，发送请求
$response = $instance->chain('v3/pay/partner/transactions/native')->post([
  'json' => [
    'sp_appid'       => 'wxdace645e0bc2cXXX',
    'sp_mchid'       => '1900006XXX',
    'sub_mchid'      => '1900007xxx',
    'description'    => 'Image形象店-深圳腾大-QQ公仔',
    'out_trade_no'   => 'native12177525012014070332333',
    'amount'         => [
      'total'    => 1,
      'currency' => 'CNY',
    ],
    'notify_url'     => 'https://weixin.qq.com/',
  ],
  // 在http请求增加一个Wechatpay-Serial请求头，具体作用可参考：https://pay.weixin.qq.com/doc/v3/merchant/4012154180.md#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
  'headers' => [
    'Wechatpay-Serial' => '134912410000000000000xxxxxxx',
  ],
]);
print_r(json_decode((string) $response->getBody(), true));

//当程序进入「异常捕获」逻辑，输出形如：
{
    "code": "RESOURCE_NOT_EXISTS",
    "message": "无可用的平台证书，请在商户平台-API安全申请使用微信支付公钥。"
}
//即表示商户仅能使用微信支付公钥初始化模式
```
```
<?php

require_once('vendor/autoload.php');

use WeChatPay\Builder;
use WeChatPay\Crypto\Rsa;

// 设置参数

// 商户号
$merchantId = '190000****';

// 从本地文件中加载「商户API私钥」，「商户API私钥」会用来生成请求的签名
$merchantPrivateKeyFilePath = 'file:///path/to/merchant/apiclient_key.pem';
$merchantPrivateKeyInstance = Rsa::from($merchantPrivateKeyFilePath, Rsa::KEY_TYPE_PRIVATE);

// 「商户API证书」的「证书序列号」
$merchantCertificateSerial = '3775B6A45ACD588826D15E583A95F5DD********';

//从本地文件中加载「微信支付公钥」，用来验证微信支付应答的签名
$platformPublicKeyFilePath = 'file:///path/to/wechatpay/publickey.pem';
$twoPlatformPublicKeyInstance = Rsa::from($platformPublicKeyFilePath, Rsa::KEY_TYPE_PUBLIC);

// 「微信支付公钥」的「微信支付公钥ID」
// 需要在 商户平台 -> 账户中心 -> API安全 查询
$platformPublicKeyId = 'PUB_KEY_ID_01142321349124100000000000********';

// 构造一个 APIv3 客户端实例
$instance = Builder::factory([
    'mchid'      => $merchantId,
    'serial'     => $merchantCertificateSerial,
    'privateKey' => $merchantPrivateKeyInstance,
    'certs'      => [
        $platformPublicKeyId => $twoPlatformPublicKeyInstance,
    ],
]);

// 以 Native 支付为例，发送请求
$response = $instance->chain('v3/pay/partner/transactions/native')->post([
  'json' => [
    'sp_appid'       => 'wxdace645e0bc2cXXX',
    'sp_mchid'       => '1900006XXX',
    'sub_mchid'      => '1900007xxx',
    'description'    => 'Image形象店-深圳腾大-QQ公仔',
    'out_trade_no'   => 'native12177525012014070332333',
    'amount'         => [
      'total'    => 1,
      'currency' => 'CNY',
    ],
    'notify_url'     => 'https://weixin.qq.com/',
  ],
  // 在http请求增加一个Wechatpay-Serial请求头，具体作用可参考：https://pay.weixin.qq.com/doc/v3/merchant/4012154180.md#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
  'headers' => [
    'Wechatpay-Serial' => 'PUB_KEY_ID_0114232134912410000000000000',
  ],
]);
print_r(json_decode((string) $response->getBody(), true));
```

## 联系 SDK 团队获取帮助

- 在[开发者社区](https://developers.weixin.qq.com/community/pay)提交问题

- 在 GitHub 上[提交 issue](https://github.com/wechatpay-apiv3/wechatpay-php/issues)

- 联系我们的[在线技术支持](https://support.pay.weixin.qq.com/aidevhelper)


## 接下来阅读

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