wechatpayv3

library2.0.3pypypi✓ verified 25d ago

Community Python SDK for WeChat Pay API v3 — the de-facto standard for WeChat Pay v3 integration in Python. Covers direct merchant mode and service provider (partner) mode. Handles RSA signature generation, platform certificate auto-download and rotation, sensitive field encryption, and callback verification/decryption automatically. IMPORTANT: Multiple competing packages exist on PyPI (wechat_pay, pywechatpay, wechatpy, pywe-pay). Only 'wechatpayv3' targets the v3 API and is actively maintained. NOTE: This is a community SDK — WeChat Pay has no official Python SDK.

payments auth-security communication http-networking

pip install wechatpayv3

github ↗package ↗

INSTALL

IMPORT

SIG · WECHATPAYV3

wechatpayv3

paymentspythonv2.0.3

Install

3.8s avg

Import

391ms

Disk

41MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 0.396s · 42.3MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 3.8s · import 0.387s · 43MB

41MB installed

● package 41MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

WeChatPay, WeChatPayType

✓ from wechatpayv3 import WeChatPay, WeChatPayType

✗ from wechatpay import WeChatPay

The wrong import pulls from 'wechat_pay', a v2-era abandoned package with a completely different API.

All amounts are in fen (smallest CNY unit). 100 fen = 1 CNY. NOTIFY_URL must be a publicly accessible HTTPS endpoint — localhost will not work. cert_dir should point to a persistent directory in production to avoid re-downloading platform certificates on every restart.

import os from wechatpayv3 import WeChatPay, WeChatPayType # Required credentials — all must be obtained from WeChat Pay Merchant Platform MCHID = os.environ['WECHAT_MCHID'] # Merchant ID PRIVATE_KEY = os.environ['WECHAT_PRIVATE_KEY'] # RSA private key (PEM string) CERT_SERIAL_NO = os.environ['WECHAT_CERT_SERIAL_NO'] # Certificate serial number APPID = os.environ['WECHAT_APPID'] # WeChat App ID APIV3_KEY = os.environ['WECHAT_APIV3_KEY'] # API v3 key (32 bytes) NOTIFY_URL = os.environ['WECHAT_NOTIFY_URL'] # Publicly accessible HTTPS endpoint # Initialize — cert_dir caches platform certificates locally wxpay = WeChatPay( wechatpay_type=WeChatPayType.NATIVE, # QR code pay mchid=MCHID, private_key=PRIVATE_KEY, cert_serial_no=CERT_SERIAL_NO, apiv3_key=APIV3_KEY, appid=APPID, notify_url=NOTIFY_URL, cert_dir='./cert' # Set to None during initial debug only ) # Native pay (QR code) — returns code_url, convert to QR for user to scan code, message = wxpay.pay( description='Order description', out_trade_no='YOUR_UNIQUE_ORDER_ID', amount={'total': 100}, # Amount in fen (1 CNY = 100 fen) pay_type=WeChatPayType.NATIVE ) # JSAPI pay (in WeChat app / WeChat browser) — requires user openid code, message = wxpay.pay( description='Order description', out_trade_no='YOUR_UNIQUE_ORDER_ID', amount={'total': 100}, pay_type=WeChatPayType.JSAPI, payer={'openid': 'USER_OPENID'} ) # Query order code, message = wxpay.query(out_trade_no='YOUR_UNIQUE_ORDER_ID') # Refund code, message = wxpay.refund( out_refund_no='YOUR_UNIQUE_REFUND_ID', out_trade_no='YOUR_UNIQUE_ORDER_ID', amount={'refund': 100, 'total': 100, 'currency': 'CNY'} ) # Async usage (FastAPI example) from wechatpayv3 import AsyncWeChatPay, WeChatPayType async def create_payment(): wxpay = AsyncWeChatPay( wechatpay_type=WeChatPayType.NATIVE, mchid=MCHID, private_key=PRIVATE_KEY, cert_serial_no=CERT_SERIAL_NO, apiv3_key=APIV3_KEY, appid=APPID, notify_url=NOTIFY_URL ) code, message = await wxpay.pay( description='Order description', out_trade_no='YOUR_UNIQUE_ORDER_ID', amount={'total': 100}, pay_type=WeChatPayType.NATIVE ) return code, message

Debug

Known issues

breakingWeChat Pay requires a Chinese business entity or a licensed overseas merchant partner to obtain merchant credentials (MCHID, API keys, certificates). Individual developers and non-Chinese companies cannot register directly. Overseas merchants must integrate via an authorized payment service provider (e.g. Stripe, Adyen, or a local aggregator) who handles the WeChat Pay merchant relationship.

fix

Verify merchant eligibility before starting integration. If you are a non-Chinese business, engage a WeChat Pay licensed partner. Integration code will work once valid credentials are obtained.

affects: all

breakingv2.0.0 (Jul 2025) introduced breaking changes from v1.3.x. The jump from 1.3.11 to 2.0.0 occurred in a single day (Jul 29–30, 2025) with no deprecation period.

fix

Pin to 2.0.1: pip install wechatpayv3==2.0.1. Review changelog at github.com/minibear2021/wechatpay-python before upgrading from v1.x.

affects: < 2.0.0

gotchaMultiple PyPI packages share similar names: 'wechat_pay' (v2-era, abandoned), 'pywechatpay' (community v3, different API), 'wechatpy' (WeChat platform SDK, not Pay-specific), 'pywe-pay' (unmaintained). Only 'wechatpayv3' targets the v3 API and is actively maintained.

fix

Install only 'wechatpayv3'. Verify with: pip show wechatpayv3 — author should be 'minibear'.

affects: all

gotchaNOTIFY_URL must be a publicly accessible HTTPS URL. WeChat Pay servers will POST payment results to this endpoint. HTTP (non-TLS) is rejected. localhost, 127.0.0.1, and private IPs will silently fail — your callback will never fire.

fix

Use a real domain with valid TLS in production. For local development use ngrok or similar tunneling.

affects: all

gotchaAll monetary amounts are in fen (分), the smallest CNY unit. 1 CNY = 100 fen. Passing amounts in CNY (e.g. 10.00 instead of 1000) will result in payments 100x smaller than intended with no error thrown.

fix

Always convert to fen before passing to the SDK: amount_fen = int(amount_cny * 100).

affects: all

gotchaOfficial WeChat Pay documentation is Chinese-first (zh-CN). The English translation at pay.weixin.qq.com lags behind and is incomplete — some v3 endpoints and error codes are only documented in Chinese.

fix

Use the Chinese docs at pay.weixin.qq.com as the source of truth. For error codes, refer to the zh-CN error code reference directly.

affects: all

gotchacert_dir set to None disables local certificate caching. On every WeChatPay instantiation, the SDK will re-download platform certificates from WeChat servers. In production or serverless environments with frequent cold starts, this causes latency and risks hitting WeChat's certificate download rate limits.

fix

Always set cert_dir to a persistent directory path in production. In serverless (Lambda, Cloud Run), use a shared volume or pre-cache certificates at build time.

affects: all

breakingThe SDK requires merchant credentials (MCHID, serial_no, apiv3_key, private_key) to be provided at runtime, typically via environment variables or a configuration file. Failing to set these will result in a KeyError or similar configuration error, preventing the SDK from initializing.

fix

Ensure all required environment variables (WECHAT_MCHID, WECHAT_SERIAL_NO, WECHAT_APIV3_KEY, WECHAT_PRIVATE_KEY) are correctly set before running the application. Alternatively, pass these credentials directly to the WeChatPay constructor during initialization.

affects: all

breakingEssential credentials such as MCHID (Merchant ID), API key, and certificate path are required for the SDK to initialize. These are typically loaded from environment variables (e.g., WECHAT_MCHID) or a configuration file. Failure to provide them will result in a KeyError or similar configuration error upon application startup.

fix

Ensure that all necessary WeChat Pay credentials (MCHID, API key, certificate and private key paths) are correctly configured and accessible to your application, either through environment variables (as expected by the script) or other secure configuration methods.

affects: all

Upgrade

Version history

2.0.3latest on PyPI · released Jul 18, 2026

Audit

Dependencies

requestsrequiredRequired. Used for sync HTTP transport.

cryptographyrequiredRequired. RSA signing, certificate handling, sensitive field encryption.

httpxoptionalRequired for async variant only.

Agent activity

111 hits · last 30 days

node

Resources

githubhttps://github.com/minibear2021/wechatpayv3 ↗

packagehttps://pypi.org/project/wechatpayv3/ ↗