Package: wechatpayv3-fix
【修复版 v1.2.36】微信支付 API v3 Python SDK介绍微信支付接口 V3 版 python 库。适用对象wechatpayv3同时支持微信支付直连模式及服务商模式，接口说明详见官网。特性平台证书自动更新，无需开发者关注平台证书有效性，无需手动下载更新；支持本地缓存平台证书，初始化时指定平台证书保存目录即可；敏感信息直接传入明文参数，SDK 内部自动加密，无需手动处理；回调通知自动验证回调消息，自动解密 resource 对象，并返回解密后的数据；已适配直连模式和服务商模式中除“电商收付通”以外所有 v3 版接口。安装$ pip install wechatpayv3-fix使用方法准备参考微信官方文档准备好密钥, 证书文件和配置(证书/密钥/签名介绍)商户 API 证书私钥：PRIVATE_KEY。商户申请商户 API 证书时，会生成商户私钥，并保存在本地证书文件夹的文件 apiclient_key.pem 中。:warning: 不要把私钥文件暴露在公共场合，如上传到 Github，写在客户端代码等。商户 API 证书序列号：CERT_SERIAL_NO。每个证书都有一个由 CA 颁发的唯一编号，即证书序列号。扩展阅读如何查看证书序列号。微信支付 APIv3 密钥：APIV3_KEY，是在回调通知和微信支付平台证书下载接口中，为加强数据安全，对关键信息AES-256-GCM加密时使用的对称加密密钥。一个最小的后端examples.py演示了一个带有Native 支付下单接口和支付通知接口的后端。
首先，修改examplys.py里以下几项配置参数：# 微信支付商户号，服务商模式下为服务商户号，即官方文档中的sp_mchid。MCHID='1230000109'# 商户证书私钥，此文件不要放置在下面设置的CERT_DIR目录里。withopen('path_to_key/apiclient_key.pem')asf:PRIVATE_KEY=f.read()# 商户证书序列号CERT_SERIAL_NO='444F4864EA9B34415...'# API v3密钥， https://pay.weixin.qq.com/wiki/doc/apiv3/wechatpay/wechatpay3_2.shtmlAPIV3_KEY='MIIEvwIBADANBgkqhkiG9w0BAQE...'# APPID，应用ID，服务商模式下为服务商应用ID，即官方文档中的sp_appid，也可以在调用接口的时候覆盖。APPID='wxd678efh567hg6787'# 回调地址，也可以在调用接口的时候覆盖。NOTIFY_URL='https://www.xxxx.com/notify'# 微信支付平台证书缓存目录，初始调试的时候可以设为None，首次使用确保此目录为空目录。CERT_DIR='./cert'# 日志记录器，记录web请求和回调细节，便于调试排错。logging.basicConfig(filename=os.path.join(os.getcwd(),'demo.log'),level=logging.DEBUG,filemode='a',format='%(asctime)s-%(process)s-%(levelname)s:%(message)s')LOGGER=logging.getLogger("demo")# 接入模式：False=直连商户模式，True=服务商模式。PARTNER_MODE=False# 代理设置，None或者{"https": "http://10.10.1.10:1080"}，详细格式参见https://docs.python-requests.org/zh_CN/latest/user/advanced.htmlPROXY=None接下来初始化 WechatPay 实例并配置一个合适的接口：wxpay=WeChatPay(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,cert_dir=CERT_DIR,logger=LOGGER,partner_mode=PARTNER_MODE,proxy=PROXY)app=Flask(__name__)@app.route('/pay')defpay():# 以native下单为例，下单成功后即可获取到'code_url'，将'code_url'转换为二维码，并用微信扫码即可进行支付测试。out_trade_no=''.join(sample(ascii_letters+digits,8))description='demo-description'amount=1code,message=wxpay.pay(description=description,out_trade_no=out_trade_no,amount={'total':amount},pay_type=WeChatPayType.NATIVE)returnjsonify({'code':code,'message':message})检查一下参数无误，现在就可以用 python 解释器来运行：$pythonexamples.py*ServingFlaskapp"examples"(lazyloading)*Environment:productionWARNING:Thisisadevelopmentserver.Donotuseitinaproductiondeployment.UseaproductionWSGIserverinstead.*Debugmode:off*Runningonhttp://127.0.0.1:5000/(PressCTRL+Ctoquit)现在访问http://127.0.0.1:5000/pay，如果一切正常，你会看到下面一串 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 接口列表如下，部分接口调用示例可以参考这里：大类小类接口接口函数直连商户适用服务商适用公用公用调起支付签名sign是是公用公用回调通知callback是是公用公用敏感信息参数解密decrypt是是公用公用下载账单download_bill是是商户进件特约商户进件、小微商户进件提交申请单applyment_submit否是商户进件特约商户进件、小微商户进件查询申请单状态applyment_query否是商户进件特约商户进件、小微商户进件修改结算账号applyment_settlement_modify否是商户进件特约商户进件、小微商户进件查询结算账号applyment_settlement_query否是基础支付JSAPI、APP、H5、Native、小程序支付统一下单pay是是基础支付JSAPI、APP、H5、Native、小程序支付查询订单query是是基础支付JSAPI、APP、H5、Native、小程序支付关闭订单close是是基础支付合单支付统一下单combine_pay是是基础支付合单支付查询订单combine_query是是基础支付合单支付关闭订单combine_close是是基础支付JSAPI、APP、H5、Native、小程序、合单支付申请退款refund是是基础支付JSAPI、APP、H5、Native、小程序、合单支付查询单笔退款query_refund是是基础支付JSAPI、APP、H5、Native、小程序、合单支付申请交易账单trade_bill是是基础支付JSAPI、APP、H5、Native、小程序、合单支付申请资金账单fundflow_bill是是基础支付JSAPI、APP、H5、Native、小程序、合单支付申请单个子商户资金账单submch_fundflow_bill否是基础支付JSAPI、APP、H5、Native、小程序、合单支付下载账单download_bill是是经营能力微信支付分（免确认模式）创单结单合并payscore_direct_complete是否经营能力微信支付分（免确认预授权模式）商户预授权payscore_permission是否经营能力微信支付分（免确认预授权模式）查询用户授权记录payscore_permission_query是否经营能力微信支付分（免确认预授权模式）解除用户授权关系payscore_permission_terminate是否经营能力微信支付分（公共 API）创建支付分订单payscore_create是否经营能力微信支付分（公共 API）查询支付分订单payscore_query是否经营能力微信支付分（公共 API）取消支付分订单payscore_cancel是否经营能力微信支付分（公共 API）修改订单金额payscore_modify是否经营能力微信支付分（公共 API）完结支付分订单payscore_complete是否经营能力微信支付分（公共 API）商户发起催收扣款payscore_pay是否经营能力微信支付分（公共 API）同步服务订单信息payscore_sync是否经营能力微信支付分（公共 API）申请退款payscore_refund是否经营能力微信支付分（公共 API）查询单笔退款payscore_refund_query是否经营能力微信支付分（公共 API）商户申请获取对账单payscore_merchant_bill是否经营能力支付即服务服务人员注册guides_register是是经营能力支付即服务服务人员分配guides_assign是是经营能力支付即服务服务人员查询guides_query是是经营能力支付即服务服务人员信息更新guides_update是是经营能力点金计划点金计划管理goldplan_plan_change否是经营能力点金计划商家小票管理goldplan_custompage_change否是经营能力点金计划同业过滤标签管理goldplan_advertising_filter否是经营能力点金计划开通广告展示goldplan_advertising_open否是经营能力点金计划关闭广告展示goldplan_advertising_close否是行业方案电商收付通尚未适配尚未适配否是行业方案智慧商圈商圈积分同步points_notify是是行业方案智慧商圈商圈积分授权查询user_authorization是是行业方案智慧商圈商圈会员待积分状态查询business_point_status是是行业方案智慧商圈商圈会员停车状态同步business_parking_sync是是行业方案微信支付分停车服务查询车牌服务开通信息parking_service_find是是行业方案微信支付分停车服务创建停车入场parking_enter是是行业方案微信支付分停车服务扣费受理parking_order是是行业方案微信支付分停车服务查询订单parking_query是是营销工具代金券创建代金券批次marketing_favor_stock_create是是营销工具代金券激活代金券批次marketing_favor_stock_start是是营销工具代金券发放代金券批次marketing_favor_stock_send是是营销工具代金券暂停代金券批次marketing_favor_stock_pause是是营销工具代金券重启代金券批次marketing_favor_stock_restart是是营销工具代金券条件查询批次列表marketing_favor_stock_list是是营销工具代金券查询批次详情marketing_favor_stock_detail是是营销工具代金券查询代金券详情marketing_favor_coupon_detail是是营销工具代金券查询代金券可用商户marketing_favor_stock_merchant是是营销工具代金券查询代金券可用单品marketing_favor_stock_item是是营销工具代金券根据商户号查用户的券marketing_favor_user_coupon是是营销工具代金券下载批次核销明细marketing_favor_use_flow是是营销工具代金券下载批次退款明细marketing_favor_refund_flow是是营销工具代金券设置消息通知地址marketing_favor_callback_update是是营销工具商家券创建商家券marketing_busifavor_stock_create是是营销工具商家券查询商家券详情marketing_busifavor_stock_query是是营销工具商家券核销用户券marketing_busifavor_coupon_use是是营销工具商家券根据过滤条件查询用户券marketing_busifavor_user_coupon是是营销工具商家券查询用户单张券详情marketing_busifavor_coupon_detail是是营销工具商家券上传预存 codemarketing_busifavor_couponcode_upload是是营销工具商家券设置商家券事件通知地址marketing_busifavor_callback_update是是营销工具商家券查询商家券事件通知地址marketing_busifavor_callback_query是是营销工具商家券关联订单信息marketing_busifavor_coupon_associate是是营销工具商家券取消关联订单信息marketing_busifavor_coupon_disassociate是是营销工具商家券修改批次预算marketing_busifavor_stock_budget是是营销工具商家券修改商家券基本信息marketing_busifavor_stock_modify是是营销工具商家券申请退券marketing_busifavor_coupon_return是是营销工具商家券使券失效marketing_busifavor_coupon_deactivate是是营销工具商家券营销补差付款marketing_busifavor_subsidy_pay是是营销工具商家券查询营销补差付款单详情marketing_busifavor_subsidy_query是是营销工具委托营销建立合作关系marketing_partnership_build是是营销工具委托营销查询合作关系列表marketing_partnership_query是是营销工具消费卡发放消费卡marketing_card_send是否营销工具支付有礼创建全场满额送活动marketing_paygift_activity_create是是营销工具支付有礼查询活动详情接口marketing_paygift_activity_detail是是营销工具支付有礼查询活动发券商户号marketing_paygift_merchants_list是是营销工具支付有礼查询活动指定商品列表marketing_paygift_goods_list是是营销工具支付有礼终止活动marketing_paygift_activity_terminate是是营销工具支付有礼新增活动发券商户号marketing_paygift_merchant_add是是营销工具支付有礼获取支付有礼活动列表marketing_paygift_activity_list是是营销工具支付有礼删除活动发券商户号marketing_paygift_merchant_delete是是营销工具银行定向活促出行券切卡组件预下单industry_coupon_token否是营销工具银行定向活促导入定向用户协议号bank_package_file否是营销工具图片上传图片上传(营销专用)marketing_image_upload是是资金应用商家转账到零钱发起商家转账transfer_batch是否资金应用商家转账到零钱微信批次单号查询批次单transfer_query_batchid是否资金应用商家转账到零钱微信明细单号查询明细单transfer_query_detail_id是否资金应用商家转账到零钱商家批次单号查询批次单transfer_query_out_batch_no是否资金应用商家转账到零钱商家明细单号查询明细单transfer_query_out_detail_no是否资金应用商家转账到零钱转账电子回单申请受理transfer_bill_receipt是否资金应用商家转账到零钱查询转账电子回单transfer_query_bill_receipt是否资金应用商家转账到零钱转账明细电子回单受理transfer_detail_receipt是否资金应用商家转账到零钱查询转账明细电子回单受理结果transfer_query_receipt是否资金应用分账请求分账profitsharing_order是是资金应用分账查询分账结果profitsharing_order_query是是资金应用分账请求分账回退profitsharing_return是是资金应用分账查询分账回退结果profitsharing_return_query是是资金应用分账解冻剩余资金profitsharing_unfreeze是是资金应用分账查询剩余待分金额profitsharing_amount_query是是资金应用分账查询最大分账比例profitsharing_config_query否是资金应用分账添加分账接收方profitsharing_add_receiver是是资金应用分账删除分账接收方profitsharing_delete_receiver是是资金应用分账申请分账账单profitsharing_bill是是资金应用分账下载账单download_bill是是资金应用连锁品牌分账请求分账brand_profitsharing_order否是资金应用连锁品牌分账查询分账结果brand_profitsharing_order_query否是资金应用连锁品牌分账请求分账回退brand_profitsharing_return否是资金应用连锁品牌分账查询分账回退结果brand_profitsharing_return_query否是资金应用连锁品牌分账完结分账brand_profitsharing_unfreeze否是资金应用连锁品牌分账查询剩余待分金额brand_profitsharing_amount_query否是资金应用连锁品牌分账查询最大分账比例brand_profitsharing_config_query否是资金应用连锁品牌分账添加分账接收方brand_profitsharing_add_receiver否是资金应用连锁品牌分账删除分账接收方brand_profitsharing_delete_receiver否是资金应用连锁品牌分账申请分账账单profitsharing_bill否是资金应用连锁品牌分账下载账单download_bill是是风险合规商户开户意愿确认提交申请单apply4subject_submit否是风险合规商户开户意愿确认撤销申请单apply4subject_cancel否是风险合规商户开户意愿确认查询申请单审核结果apply4subject_query否是风险合规商户开户意愿确认获取商户开户意愿确认状态apply4subject_state否是风险合规消费者投诉 2.0查询投诉单列表complaint_list_query是是风险合规消费者投诉 2.0查询投诉单详情complaint_detail_query是是风险合规消费者投诉 2.0查询投诉协商历史complaint_history_query是是风险合规消费者投诉 2.0创建投诉通知回调地址complaint_notification_create是是风险合规消费者投诉 2.0查询投诉通知回调地址complaint_notification_query是是风险合规消费者投诉 2.0更新投诉通知回调地址complaint_notification_update是是风险合规消费者投诉 2.0删除投诉通知回调地址complaint_notification_delete是是风险合规消费者投诉 2.0提交回复complaint_response是是风险合规消费者投诉 2.0反馈处理完成complaint_complete是是风险合规消费者投诉 2.0更新退款审批结果complaint_update_refund是是风险合规消费者投诉 2.0商户上传反馈图片complaint_image_upload是是风险合规消费者投诉 2.0图片下载complaint_image_download是是风险合规商户违规通知回调创建商户违规通知回调地址merchantrisk_callback_create否是风险合规商户违规通知回调查询商户违规通知回调地址merchantrisk_callback_query否是风险合规商户违规通知回调修改商户违规通知回调地址merchantrisk_callback_update否是风险合规商户违规通知回调删除商户违规通知回调地址merchantrisk_callback_delete否是其他能力图片上传图片上传image_upload是是其他能力视频上传视频上传video_upload是是其他电子发票（公共API）创建电子发票卡券模板fapiao_card_template是是其他电子发票（公共API）配置开发选项fapiao_set_merchant_config是是其他电子发票（公共API）查询商户配置的开发选项fapiao_merchant_config是是其他电子发票（公共API）获取抬头填写链接fapiao_title_url是是其他电子发票（公共API）获取用户填写的抬头fapiao_title是是其他电子发票(区块链模式)获取商品和服务税收分类对照表fapiao_tax_codes是是其他电子发票(区块链模式)获取商户开票基础信息fapiao_merchant_base_info是是其他电子发票(区块链模式)开具电子发票fapiao_applications是是其他电子发票(区块链模式)查询电子发票fapiao_query是是其他电子发票(区块链模式)冲红电子发票fapiao_reverse是是其他电子发票(自建平台模式)上传电子发票文件fapiao_upload_file是是其他电子发票(自建平台模式)将电子发票插入微信用户卡包fapiao_insert_cards是是其他银行组件获取对私银行卡号开户银行capital_search_bank_number是是其他银行组件查询支持个人业务的银行列表capital_personal_banks是是其他银行组件查询支持对公业务的银行列表capital_corporate_banks是是其他银行组件查询省份列表capital_provinces是是其他银行组件查询城市列表capital_cities是是其他银行组件查询支行列表capital_branches是是接口函数参数参数类型对照参考下表：微信支付官方文档声明wechatpayv3 python sdkstringstrintintobjectdict: {}arraylist: []booleanbool: True, Falsemessagebytes接口函数返回值每个接口均同步返回 code 和 message，code 为 web 请求得到的 HTTP 状态码，message 为服务器返回的 json 字符串。
例外：回调通知（callback）接口将收到的参数解密后返回，回调验证不合规或解密失败则返回 None；下载账单（download_bill）和消费者投诉 2.0 的图片下载（complaint_image_download）接口返回的 message 为 bytes 类型，直接将 message 写入磁盘即可获得对应的目标文件。常见问题回调验证失败处理开发者遇到的难点之一就是回调验证失败的问题，由于众多的 python web 框架对回调消息的处理不完全一致，如果出现回调验证失败，请务必确认传入的 headers 和 body 的值和类型。
通常框架传过来的 headers 类型是 dict，而 body 类型是 bytes。flask 框架参考以下方法可直接获取到解密后的实际内容。@app.route('/notify',methods=['POST'])defnotify():result=wxpay.callback(request.headers,request.data)ifresultandresult.get('event_type')=='TRANSACTION.SUCCESS':resource=result.get('resource')appid=resource.get('appid')mchid=resource.get('mchid')out_trade_no=resource.get('out_trade_no')transaction_id=resource.get('transaction_id')trade_type=resource.get('trade_type')trade_state=resource.get('trade_state')trade_state_desc=resource.get('trade_state_desc')bank_type=resource.get('bank_type')attach=resource.get('attach')success_time=resource.get('success_time')payer=resource.get('payer')amount=resource.get('amount').get('total')# TODO: 根据返回参数进行必要的业务处理，处理完后返回200或204returnjsonify({'code':'SUCCESS','message':'成功'})else:returnjsonify({'code':'FAILED','message':'失败'}),500flask 框架如上面示例，直接传入 request.headers 和 request.data 即可。result=wxpay.callback(headers=request.headers,body=request.data)django 框架由于 django 框架特殊性，会将 headers 做一定的预处理，可以参考以下方式调用。headers={}headers.update({'Wechatpay-Signature':request.META.get('HTTP_WECHATPAY_SIGNATURE')})headers.update({'Wechatpay-Timestamp':request.META.get('HTTP_WECHATPAY_TIMESTAMP')})headers.update({'Wechatpay-Nonce':request.META.get('HTTP_WECHATPAY_NONCE')})headers.update({'Wechatpay-Serial':request.META.get('HTTP_WECHATPAY_SERIAL')})result=wxpay.callback(headers=headers,body=request.body)tornado 框架直接传入 request.headers 和 request.body 即可。result=wxpay.callback(headers=request.headers,body=request.body)其他框架参考以上处理方法，大原则就是保证传给 callback 的参数值和收到的值一致，不要转换为 dict，也不要转换为 string。反复收到同一个回调消息怎么处理实际开发中处理微信支付通知消息时有两个问题需要注意。一是可能会重复收到同一个通知消息，需要在代码中进行判断处理。另一个是处理消息的时间如果过长，建议考虑异步处理，先缓存消息，避免微信支付服务器端认为超时，如果持续超时，微信支付服务器端可能会认为回调消息接口不可用。接口清单里怎么没有回调接口所有的回调接口都通过公用接口 callback 处理，因此清单里没有一一罗列。对于收到的回调消息，可以通过 event_type 参数判断消息类型进行下一步处理，具体参数清单参考微信支付官方文档。服务商模式如何接入SDK 默认为直连商户接入，如果初始化时候指定 partner_mode=True，即切换为服务商模式。需要注意的是，一部分接口为直连商户专有，一部分接口为服务商模式专有，另有部分接口同时兼容直连商户和服务商，这些同时兼容的接口在两种模式下个别参数要求会稍有不同。如何下载平台证书？SDK 内部已经实现了自动下载和加载平台证书，无需预先下载。如需了解具体实现逻辑，可以参阅core.py中的_update_certificates 函数。接口始终返回 500 错误通常为初始化参数配置错误，如果反复检查无果，建议进入微信支付后台重置所有参数后再试。回调接口始终校验失败查阅 web 框架文档，确保传入 callback 的 body 参数没有经过任何转义，通常为 bytes 类型。下载平台证书时解析失败检查 APIV3_KEY 是否和微信支付后台设置的一致，如无法确认，建议重置后再试。签名、验签、加密、解密的内部实现一般应用开发者可以不用向下看了，有心了解这几项内部实现的可以参考这里了解。