更新记录
0.3.0(2026-11-19)
- 新增微信外部浏览器 H5、公众号 JSAPI 和电脑 Native 扫码支付,服务端输出可展示的二维码。
- 新增微信及支付宝部分退款,多笔退款按原单额度校验。保留旧版全额退款单和查询方式。
- 新增服务端多商户路由、微信普通服务商收款和退款,以及支付宝第三方应用代商户收款和退款。
- 更新两个模拟项目、插件定价、授权说明和上架资料。
- 插件包内提供 uni-app 和 uni-app x 的同名模拟页面,可在宿主注册运行。
平台兼容性
云端兼容性
| 支付宝云 | 腾讯云 | 阿里云 |
|---|---|---|
| × | √ | √ |
uni-app(5.26)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| × | √ | √ | - | - | - | - | - | × |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| √ | √ | - | - | - | - | - | - | - | - | - | - |
uni-app x(5.34)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| √ | - | - | - | × | √ |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | × | √ | × |
zhuanz-wxpaykit
0.3.0 支持微信、支付宝直连多商户和服务商收款。微信覆盖小程序、App、外部浏览器 H5、公众号、电脑扫码,支持普通商户转账和免确认授权。支付宝覆盖小程序、App、手机和电脑网站、当面付及账户转账。两渠道均支持全额和部分退款。
安装
- 把本模块放到宿主项目的
uni_modules/zhuanz-wxpaykit。本插件的最低兼容版本为 uni-app Vue 3 5.26 和 uni-app x 5.34,分别使用对应版本的 HBuilderX 或更新版本。后端使用 uniCloud Node.js 18。uni-app x 支付兼容表 - 在 HBuilderX 为宿主项目创建并关联自己的 uniCloud 服务空间。在插件的
uniCloud/database上传zhuanz-wxpay-orders.schema.json。使用多商户时也上传zhuanz-pay-merchants.schema.json。集合由服务端读写,Schema 关闭客户端访问。 - 为宿主的业务云函数或云对象添加
zhuanz-wxpay-core公共模块依赖,给公共模块安装package.json中的依赖。上传公共模块与所用渠道的通知云函数zhuanz-wxpay-notify、zhuanz-alipay-notify,为各通知函数启用独立的公网 HTTPS URL。这两个入口仅接收渠道通知。uniCloud URL 化 - 在服务空间或相关云函数通过环境变量配置下表。回调函数与调用公共模块的业务函数须使用同一商户配置。微信支付产品权限及小程序 AppID 绑定在商户平台办理。环境变量 · 微信商家转账开通
| 环境变量 | 内容 |
|---|---|
WXPAY_APP_ID |
已关联当前商户的小程序 AppID |
WXPAY_MCH_ID |
微信普通商户号 |
WXPAY_MERCHANT_SERIAL |
商户 API 证书序列号 |
WXPAY_MERCHANT_PRIVATE_KEY |
商户 API 证书私钥 PEM,支持用字面量 \n 表示换行 |
WXPAY_WECHAT_SERIAL |
微信支付公钥 ID,或平台证书序列号 |
WXPAY_WECHAT_PUBLIC_KEY |
对应该 ID 的微信支付公钥 PEM,或对应的平台证书 PEM |
WXPAY_API_V3_KEY |
32 字节 APIv3 密钥,用于回调解密 |
WXPAY_NOTIFY_URL |
回调函数的公网 HTTPS 地址,无查询参数 |
WXPAY_TRANSFER_SCENE_ID |
商户已获批的转账场景 ID,使用转账时填写 |
WXPAY_H5_RETURN_URL |
可选的 H5 支付返回页,HTTPS 域名必须与已配置的微信 H5 支付域名一致 |
WXPAY_SUB_MCH_ID、WXPAY_SUB_APP_ID |
微信服务商模式的特约商户号和可选子 AppID。此时 WXPAY_MCH_ID、WXPAY_APP_ID 和密钥配置为服务商资料 |
运行模拟页面
插件包自带 uni-app 的 zhuanz-pay-demo.vue 和 uni-app x 的 zhuanz-pay-demo.uvue。如果要在宿主体验模拟流程,把以下对象加入宿主 pages.json 的 pages 数组。两套工程使用相同的页面路径,模拟过程无需配置支付密钥或连接云空间。
{
"path": "uni_modules/zhuanz-wxpaykit/pages/zhuanz-pay-demo/zhuanz-pay-demo",
"style": { "navigationBarTitleText": "微信和支付宝支付" }
}
服务端调用
下列 order 和 withdrawal 由宿主服务端从已校验身份和权限的业务记录中读取。金额使用整数分,收款人绑定服务端维护的 OpenID。退款和转账等资金操作应由获授权的后台业务执行。
const { createPayKit } = require('zhuanz-wxpay-core')
const pay = createPayKit()
const payment = await pay.createPayment({
number: order.tradeNo,
amount: order.amountInFen,
openId: order.payerOpenId,
description: order.description
})
const transfer = await pay.createTransfer({
number: withdrawal.transferNo,
amount: withdrawal.approvedAmountInFen,
openId: withdrawal.recipientOpenId,
remark: withdrawal.remark,
sceneReports: withdrawal.sceneReports,
userName: withdrawal.verifiedRecipientName
})
转账报备字段 sceneReports 使用 { type, content }[],按获批场景填写。金额达到 2,000 元时需要提供服务端已核验的收款人姓名,模块会对姓名加密。转账单号使用字母和数字,复用同一业务单号时,业务金额和收款人等参数须保持一致。微信发起转账
| 方法 | 结果或用途 |
|---|---|
createPayment({ number, amount, openId, description }) |
创建或复用小程序支付单,返回 paymentParams |
createAppPayment({ number, amount, description }) |
微信 App V3 下单,返回可传给客户端的 orderInfo JSON 字符串 |
createH5Payment({ number, amount, description, payerClientIp }) |
外部手机浏览器,返回 checkout.h5Url 和 checkout.expiresAt。由宿主服务端填实际用户 IP |
createOfficialAccountPayment({ number, amount, description, openId }) |
微信内置浏览器,返回含 appId 的 paymentParams。OpenID 由宿主公众号授权获取 |
createNativePayment({ number, amount, description }) |
电脑扫码,返回 checkout.codeUrl、checkout.qrCodeDataUrl 和 checkout.expiresAt,页面直接用图片展示 |
queryPayment(number)、closePayment(number) |
查询或关闭支付单 |
createRefund({ paymentNumber, number?, amount?, reason? }) |
提供 number 与 amount 时按指定退款单号退对应的整数分。两者省略时沿用旧版固定单号全额退款 |
queryRefund(number) |
查询退款单,参数为退款返回的 number |
createTransfer({ number, amount, openId, remark, sceneReports, userName }) |
发起转账,待收款且微信已返回 package_info 时提供 confirmationParams |
queryTransfer(number)、cancelTransfer(number) |
查询或发起撤销,撤销受理后继续查最终结果 |
createTransferAuthorization({ number, openId, displayName, recvPerception }) |
申请免确认收款,返回 confirmationParams |
queryTransferAuthorization(number, includeConfirmation?)、closeTransferAuthorization(number) |
查询授权、按需取得确认参数或解除授权 |
createAuthorizedTransfer({ ...transferInput, authorizationNumber }) |
校验同一收款人和有效授权,再向微信提交转账 |
getLocalOrder(kind, number) |
获取最近一次已经核实并落库的状态 |
handleNotify(headers, rawBody) |
验证原始报文签名、解密并幂等更新相应单据 |
当 API 超时、响应签名无效或交易状态未知时,先用原商户单号查询。确认单据状态后再决定是否用相同参数重试。宿主需要按业务定期查询未结单据,并根据最终状态更新应用订单或账本。退款异常通过商户后台处理。若通过其他渠道直接操作同一订单,宿主还需核对渠道账单。退款开发指引 · 转账开发指引
微信授权应给每位用户保存一个稳定的业务授权单号。用户在微信完成授权且服务端查询为 TAKING_EFFECT 后,后台才能按已审核的单据发起免确认转账。授权过期或解除后使用新授权单重新征得用户同意。小程序与 App 使用各自开通产品的 AppID、对应用户标识和对应的回调配置。微信授权开发指引 · 微信 App 支付
支付宝服务端
调用 require('zhuanz-wxpay-core').createAlipayKit() 获得支付宝实例。收款可在商户签约的公钥或证书模式下调用,单笔转账启用证书模式。每个实例使用单一支付宝应用与收款 PID。公钥、私钥、证书和 URL 配置在宿主业务函数及回调函数的服务端环境变量中。支付宝官方 SDK · 账户转账接口
| 环境变量 | 内容 |
|---|---|
ALIPAY_APP_ID、ALIPAY_SELLER_ID |
已签约的应用 ID 和商户收款 PID |
ALIPAY_NOTIFY_URL、ALIPAY_RETURN_URL |
收款通知地址,及可选的网页支付返回地址 |
ALIPAY_PRIVATE_KEY |
应用私钥 PEM,支持字面量 \n |
ALIPAY_PUBLIC_KEY |
公钥模式的支付宝公钥 PEM |
ALIPAY_APP_CERT、ALIPAY_PUBLIC_CERT、ALIPAY_ROOT_CERT |
证书模式的应用公钥证书、支付宝公钥证书和支付宝根证书 PEM |
ALIPAY_APP_AUTH_TOKEN、ALIPAY_MERCHANT_APP_ID |
服务商代调用时使用商户授权令牌和商户实际应用 ID。ALIPAY_APP_ID 使用第三方应用 ID,ALIPAY_SELLER_ID 为授权商户收款 PID |
| 方法 | 参数和返回值 |
|---|---|
createPayment({ number, amount, subject, channel, buyerOpenId }) |
channel 为 mini、app、wap、page 或 qr,mini 使用当前登录用户对应的支付宝 OpenID |
queryPayment(number)、closePayment(number) |
查单和关单 |
createRefund({ paymentNumber, number?, amount?, reason? })、queryRefund(number) |
全额和部分退款,按本次退款单号主动查询 |
createTransfer({ number, amount, title, identityType, identity, name, sceneName, sceneReports, remark }) |
发起到支付宝账户的单笔转账,金额为整数分。sceneReports 是 { type, content }[] |
queryTransfer(number)、getLocalOrder(kind, number) |
主动查转账及查看已核实的本地状态 |
支付宝收款的 checkout 按渠道返回 tradeNo、orderInfo、paymentUrl 或 qrCode,扫码渠道的字符串可由宿主渲染为二维码。转账 identityType 支持 ALIPAY_LOGON_ID、ALIPAY_USER_ID、ALIPAY_OPEN_ID,账号登录标识配合真实姓名。转账场景及报备字段以商户已申明的业务为准。收款通知验签后校验 app_id、seller_id、订单号和金额。退款及转账用主动查单确认结果。支付宝收款通知说明 · 支付宝转账场景
多商户与服务商
在服务端集合 zhuanz-pay-merchants 中以业务商户标识为 _id 创建记录。记录可包含 wechat、alipay 或两者。服务端从已校验归属的业务订单读取并保存 merchantKey,后续查单、关单、退款调用同一配置。业务 API 应先校验订单与用户或操作员的关系。
const { createMerchantRouter } = require('zhuanz-wxpay-core')
const router = createMerchantRouter()
const merchantPay = await router.forMerchant('wechat', savedOrder.merchantKey)
const payment = await merchantPay.createNativePayment({
number: savedOrder.tradeNo,
amount: savedOrder.amountInFen,
description: savedOrder.subject
})
按下表配置各渠道。字段值为字符串,私钥、证书和授权令牌可用 { "env": "PAYKIT_SHOP_A_KEY" } 引用云端环境变量。业务云函数与对应通知云函数需要读取相同的环境配置。
| 配置 | 字段 |
|---|---|
wechat |
appId, mchId, merchantSerial, merchantPrivateKey, wechatSerial, wechatPublicKey, apiV3Key。可选 transferSceneId, h5ReturnUrl, notifyBaseUrl |
| 微信普通服务商 | 同上,凭据使用服务商商户号,再增加 subMchId。subAppId 存在时使用其用户 OpenID,省略时使用服务商 AppID 对应的用户 OpenID |
alipay |
appId, sellerId, privateKey, alipayPublicKey 或 appCertContent, alipayPublicCertContent, alipayRootCertContent。可选 returnUrl, notifyBaseUrl |
| 支付宝第三方应用 | 同上,appId 与密钥来自第三方应用,再增加 merchantAppId 和 appAuthToken。小程序下单使用商家经营主体应用的用户 OpenID |
如商户配置未提供 notifyBaseUrl,使用 WXPAY_NOTIFY_URL 或 ALIPAY_NOTIFY_URL。路由会在地址尾追加商户标识,例如 /zhuanz-wxpay-notify/shop-a,部署时需保留子路径。已有单商户回调仍可走原地址。路由选定后,服务端会验签并核对配置中的商户身份及金额再更新单据。微信服务商的退款使用特约商户号,微信商家转账和免确认授权使用普通商户配置。支付宝服务商要求商户已完成授权和签约,网页/App 渠道下发的是支付宝 SDK 生成的签名收银串,应仅用于网关调起。微信服务商参数 · 支付宝代调用 · uniCloud URL 路由
分笔退款
每次业务退款分配唯一 number。例如原单实付 10 元,可用 R20261119001 退 300 分,再用 R20261119002 退 400 分。同一退款重试时使用相同的单号、金额和原因。插件先登记本笔额度再发起渠道退款,已占用的额度计入累计,结果不明时按原号查单。微信每笔订单最多支持 50 次部分退款,退款单确认关闭会释放占用。支付宝退款通过主动查询本笔金额确认。支付渠道返回明确成功后由宿主完成业务处理。微信支付退款最佳实践
客户端调用
业务接口按登录身份验证订单归属后,向用户返回该笔单据的 paymentParams 或 confirmationParams。客户端操作结束后向业务后端查结果,最终状态以微信查单或已验签回调为准。
import { requestWechatPayment, requestWechatTransfer } from '@/uni_modules/zhuanz-wxpaykit'
// 分别放入宿主的支付按钮和确认收款按钮处理函数
await requestWechatPayment(paymentParams)
await requestWechatTransfer(confirmationParams)
uni-app x 从 @/uni_modules/zhuanz-wxpaykit/client.uts 导入同名接口。两个入口还提供 requestWechatAuthorization(confirmationParams)、requestWechatAppPayment(orderInfo)、requestAlipayAppPayment(orderInfo)、requestAlipayMiniPayment(tradeNo) 和 Web 的 openAlipayWebPayment(paymentUrl)。App 宿主按渠道配置原生支付模块和应用标识,微信 App 侧确认收款和授权适配 Android/iOS。示例工程运行在模拟模式。uni-app x 支付 · uni-app x 确认收款
在 uni-app 或 uni-app x 的 Web 页面中,从 @/uni_modules/zhuanz-wxpaykit/web-checkout.js 导入 openWechatH5Payment(checkout.h5Url) 和 requestWechatOfficialAccountPayment(paymentParams)。前者用于微信外浏览器,后者通过微信内置 WeixinJSBridge 调起。电脑扫码用 <image :src="checkout.qrCodeDataUrl" /> 展示,并由宿主查单显示最终结果。微信 H5 · 公众号 JSAPI · 微信 Native
升级旧版本时在原服务空间先更新 zhuanz-wxpay-orders Schema,再更新收款、退款和回调所依赖的公共模块。启用多商户时增加商户配置集合。原微信、支付宝订单和全额退款单沿用已有单号,已有的全额退款记录计入累计退款额度。

收藏人数:
购买源码授权版(
导入插件并试用
赞赏(0)
下载 208
赞赏 0
下载 35312
赞赏 159
赞赏
京公网安备:11010802035340号