wechatpayv3

微信支付 API v3 Python SDK

介绍

微信支付接口 V3 版 python 库。

欢迎微信支付开发者扫码进 QQ 群(群号：973102221)讨论，欢迎提交代码，欢迎star、follow、fork：

适用对象

wechatpayv3同时支持微信支付直连模式及服务商模式，接口说明详见官网。

特性

1. 平台证书自动更新，无需开发者关注平台证书有效性，无需手动下载更新，自动验证签名（微信支付平台证书模式）；
2. 支持本地缓存平台证书，初始化时指定平台证书保存目录即可（微信支付平台证书模式）；
3. 敏感信息直接传入明文参数，SDK 内部自动加密，无需手动处理；
4. 回调通知自动验证回调消息，自动解密 resource 对象，并返回解密后的数据；
5. 已适配直连模式和服务商模式中除“电商收付通”以外所有 v3 版接口；
6. 兼容通过平台证书模式或平台公钥模式初始化，兼容证书模式向公钥模式过渡。
7. 支持Python的异步编程 async和 await，如需集成在FastAPI框架中 查看文档地址

源码

github

gitee

安装

pip install wechatpayv3

# 安装包含异步依赖的完整版本
pip install wechatpayv3[async]

使用方法

准备

首先根据Q&A第一条判断当前账户所使用的模式（微信支付平台证书模式 或 微信支付平台公钥模式）。

参考微信官方文档准备好商户证书私钥、商户证书序列号、APIv3密钥, 这些参数配置方法请参考官方文档。

• 商户 API 证书私钥：PRIVATE_KEY。商户申请商户 API 证书时，会生成商户私钥，并保存在本地证书文件夹的文件 apiclient_key.pem 中。

  :warning: 不要把私钥文件暴露在公共场合，如上传到 Github，写在客户端代码等。

• 商户 API 证书序列号：CERT_SERIAL_NO。每个证书都有一个由 CA 颁发的唯一编号，即证书序列号。扩展阅读 如何查看证书序列号。
• 微信支付 APIv3 密钥：APIV3_KEY，是在回调通知和微信支付平台证书下载接口中，为加强数据安全，对关键信息 AES-256-GCM 解密时使用的对称加密密钥。

对于使用微信支付平台公钥模式初始化的情况，还需要从微信支付后台的“API安全”菜单中下载/复制以下两项：

• 微信支付平台公钥：PUBLIC_KEY，微信支付后台“API安全-微信支付公钥”菜单中下载的微信支付公钥。
• 微信支付平台公钥ID：PUBLIC_KEY_ID，微信支付后台“API安全-微信支付公钥”菜单中复制的微信支付公钥ID，形如：PUB_KEY_ID_1234567890...。

一个最小的后端

examples.py 演示了一个带有Native 支付下单接口和支付通知接口的后端。 首先，修改 examplys.py 里以下几项配置参数：

…

接下来使用微信支付平台证书模式初始化 WechatPay 实例并配置一个合适的接口：

…

检查一下参数无误，现在就可以用 python 解释器来运行：

$ python examples.py
 * Serving Flask app "examples" (lazy loading)
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

现在访问 ，如果一切正常，你会看到下面一串 json 字符串：

{
  "code": 200,
  "message": "{\"code_url\":\"weixin://wxpay/bizpayurl?pr=abcdefghi\"}"
}

到这一步统一下单的后端就完成了，现在将 code_url 的值即"weixin://wxpay/bizpayurl?pr=abcdefghi"用草料转换为二维码即可用微信扫码进行支付测试。

以上步骤如果不能正确执行，务必仔细检查各项初始化参数，必要的情况下，登录微信支付后台，将所有参数重置。

Native 支付调试最简单便捷，调试通过没有问题证明初始化参数正确之后，如果需要采用其他（小程序、H5、JSAPI、APP）支付下单，可继续参考 examples.py。

以上演示了一个最简单的后端，如果需要使用异步调用，可以点击查看异步版本的实现指南。

常见问题

日常开发对接中的常见问题（特别是涉及平台证书、平台公钥、回调验证失败等情况的处理）请见这里。

接口清单

已适配的微信支付 V3 版 API 接口列表明细详见这里。

部分接口的具体调用方法可以参考这里。

所有接口的参数类型和值强烈建议仔细看一下官方的接口文档。

接口函数参数

参数类型对照参考下表：

接口函数返回值

每个接口均同步返回 code 和 message，code 为 web 请求得到的 HTTP 状态码，message 为服务器返回的 json 字符串。 例外：

1. 回调通知（callback）接口将收到的参数解密后返回，回调验证不合规或解密失败则返回 None；
2. 下载账单（download_bill）和消费者投诉 2.0 的图片下载（complaint_image_download）接口返回的 message 为 bytes 类型，直接将 message 写入磁盘即可获得对应的目标文件。
3. 账单下载接口默认返回的是gzip格式的文件，可用gzip库解压后获取实际的账单文件。