更新记录

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、手机和电脑网站、当面付及账户转账。两渠道均支持全额和部分退款。

安装

  1. 把本模块放到宿主项目的 uni_modules/zhuanz-wxpaykit。本插件的最低兼容版本为 uni-app Vue 3 5.26 和 uni-app x 5.34,分别使用对应版本的 HBuilderX 或更新版本。后端使用 uniCloud Node.js 18。uni-app x 支付兼容表
  2. 在 HBuilderX 为宿主项目创建并关联自己的 uniCloud 服务空间。在插件的 uniCloud/database 上传 zhuanz-wxpay-orders.schema.json。使用多商户时也上传 zhuanz-pay-merchants.schema.json。集合由服务端读写,Schema 关闭客户端访问。
  3. 为宿主的业务云函数或云对象添加 zhuanz-wxpay-core 公共模块依赖,给公共模块安装 package.json 中的依赖。上传公共模块与所用渠道的通知云函数 zhuanz-wxpay-notify、zhuanz-alipay-notify,为各通知函数启用独立的公网 HTTPS URL。这两个入口仅接收渠道通知。uniCloud URL 化
  4. 在服务空间或相关云函数通过环境变量配置下表。回调函数与调用公共模块的业务函数须使用同一商户配置。微信支付产品权限及小程序 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,再更新收款、退款和回调所依赖的公共模块。启用多商户时增加商户配置集合。原微信、支付宝订单和全额退款单沿用已有单号,已有的全额退款记录计入累计退款额度。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

插件不额外申请设备权限。真实交易需宿主配置网络、对应渠道的支付能力及应用标识,App 支付由宿主启用相应支付模块。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

宿主的 uniCloud 服务空间保存商户单号、交易金额、状态、渠道单号及授权记录,用于查单、退款和回调处理。交易时按需将付款人或收款人标识、转账报备信息及 H5 支付所需客户端 IP 发送至微信支付 api.mch.weixin.qq.com 或支付宝 openapi.alipay.com。模拟示例仅使用本地数据。

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。