微信虚拟支付(微信小程序)
微信虚拟支付是微信为小程序内的虚拟商品提供的收款方式,例如短剧、会员、代币、课程等。用户在小程序里购买的是你在微信后台 虚拟支付 → 基本配置 → 道具配置 中添加的道具,iOS 用户通过苹果 IAP 付款,安卓用户通过微信支付付款。
Zion 目前支持虚拟支付的 道具直购,适用于微信小程序客户端,支持单次支付和退款。开始前,请先阅读支付功能概述,准备订单表并了解支付结果的处理方式。
按微信的规定,小程序在 iOS 上售卖虚拟商品需要接入虚拟支付。如果你售卖的是实物或服务,请使用微信支付(微信小程序)。
iOS 支付限制
iOS 用户通过苹果 IAP 付款,限制比安卓多。设计道具价格、测试流程和售后方案前,请先确认以下几点:
- 只能使用正式环境:苹果 IAP 不支持沙箱环境。iOS 上的付款只能在 正式环境 中进行,购买的必须是已发布到 线上版本 的道具,否则会提示
15011。 - 单价最少 1 元:iOS 用户购买的道具,单价不能低于 1 元。
- 需要开启苹果 IAP 支付:在微信后台开启 是否启用苹果 IAP 支付 后,iOS 用户才能付款,否则会提示
15001。 - 只支持中国大陆 Apple ID:其他地区的 Apple ID 无法付款。
- 开发者不能退款:iOS 订单只能由支付者在自己手机的钱包中向苹果申请退款。通过 Zion 的退款行为发起会失败。
- 苹果退款后 Zion 收不到通知:支付者在苹果退款后,Zion 不会更新支付记录、不会生成退款记录,也不会运行 退款成功时 行为流。已发放的权益无法自动收回,请在业务上提前考虑这种情况。
开始前
开通虚拟支付
在微信公众平台 为小程序开通虚拟支付。开通条件和审核流程见微信虚拟支付文档 。
获取 AppID、OfferID 和 AppKey
打开 虚拟支付 → 基本配置 → 基础配置,记下 AppID(小程序 ID)、OfferID(支付应用 ID),并点击 查看沙箱 AppKey 和 查看现网 AppKey 获取两个 AppKey。
如果需要让 iOS 用户付款,在同一页面开启 是否启用苹果 IAP 支付。开启后大约 10 分钟生效。

添加道具
在 虚拟支付 → 基本配置 → 道具配置 中添加道具,记下每个道具的 道具 id 和 价格,后面发起支付时要用到。
- 开发版本 中的道具可以在沙箱环境中测试。
- 测试无误后把道具发布到 线上版本,正式环境只能购买线上版本中的道具。
- 需要卖给 iOS 用户的道具,价格不能低于 1 元,见 iOS 支付限制。

支付配置
新建支付配置
打开 行为 → 支付,点击 新建,填写配置名称,支付渠道 选择 微信虚拟支付,然后点击 创建并开始配置。如果这是项目中第一个支付配置,需要先绑定订单表。

填写商户信息
商户信息中的值分两类:
- 从微信获取:App ID、OfferID 和两个 AppKey 都是微信分配的,在微信公众平台打开 虚拟支付 → 基本配置 → 基础配置 查看,对应的名称分别是 AppID(小程序 ID)、OfferID(支付应用 ID)、现网 AppKey 和 沙箱 AppKey。获取方法见上文的「获取 AppID、OfferID 和 AppKey」。
- 自己设置:消息推送 Token 和 EncodingAESKey 不是从微信获取的,由你自己设置。在这里填好后,要把同样的值填到微信公众平台的消息推送配置中,见下文的配置消息推送。
在 配置 → 商户信息 中填写:
| 配置项 | 必填 | 填写方式 | 说明 |
|---|---|---|---|
| App ID | 是 | 文本 | 小程序的 AppID |
| OfferID | 是 | 文本 | 虚拟支付基础配置中的 OfferID |
| 环境 | 是 | 下拉选择 | 沙箱环境 用于测试,正式环境 用于线上收款 |
| AppKey(正式环境) | 环境为正式环境时必填 | Secret | 现网 AppKey |
| AppKey(沙箱环境) | 环境为沙箱环境时必填 | Secret | 沙箱 AppKey |
| 消息推送 Token | 是 | Secret | 自定义的字母和数字组合,稍后填写到微信公众平台的消息推送配置中 |
| 消息推送 EncodingAESKey | 否 | Secret | 自定义的 43 位字母和数字组合,稍后填写到微信公众平台的消息推送配置中 |
AppKey、Token 和 EncodingAESKey 只能绑定 Secret。点击字段右侧的 + 可以直接新建 Secret。

Zion 只处理与 环境 一致的支付通知。沙箱测试完成、准备上线时,记得把 环境 切换为 正式环境 并重新发布,否则线上的支付结果不会被处理。
选择支付产品
在 支付产品 中勾选 道具直购。

选择客户端
在 客户端管理 中勾选微信小程序的客户端。

配置支付结果处理
在 支付结果处理 中为 支付完成时 和 退款成功时 各绑定一个行为流,具体步骤见下文的配置支付结果行为流。
配置权限
打开 权限管理,按角色勾选允许通过这个配置发起的支付类型:
| 支付类型 | 默认 | 建议 |
|---|---|---|
| 单次支付 | 所有角色已开启 | 为需要付款的角色保留,例如已登录用户 |
| 退款 | 未开启 | 只为可信任的管理员角色开启 |

同步后端
点击编辑器右上角的 后端,把支付配置同步到后端。下一步在微信公众平台保存消息推送配置时,微信会立即向通知地址发送验证请求,配置没有同步时验证会失败。
配置消息推送
微信通过小程序的消息推送通知支付和退款结果。
复制通知地址
在支付配置的 支付结果处理 下方,点击 通知地址 旁的复制按钮。
填写消息推送配置
在微信公众平台打开 开发与服务 → 开发管理,找到 消息推送,启用并填写:
| 配置项 | 填写内容 |
|---|---|
| URL(服务器地址) | 上一步复制的通知地址 |
| Token(令牌) | 与支付配置中 消息推送 Token 的值相同 |
| EncodingAESKey(消息加密密钥) | 与支付配置中 消息推送 EncodingAESKey 的值相同 |
| 消息加密方式 | 明文模式 |
| 数据格式 | JSON |
点击 保存,微信会向通知地址发送验证请求,显示保存成功即配置完成。
一定要先部署 Zion 后端(点击编辑器右上角的 后端),再在微信公众平台点击 保存,否则验证不会成功。

一个小程序只能配置一个消息推送地址,而且每月修改次数有限。如果小程序的消息推送已经用于其他服务,请先确认替换后不会影响原有业务。
配置支付结果行为流
微信虚拟支付有两种支付事件:支付完成时 和 退款成功时。Zion 收到微信的通知后,先更新支付表或退款表,再运行对应的行为流。你需要在行为流中完成更新订单、发放道具对应的权益等业务。
支付完成时
微信通知道具发货后,支付记录变为 SUCCESSFUL,Zion 运行此行为流。支付失败或用户取消支付时不会运行。
添加入参
为行为流添加入参 payment_id(长整数),在支付配置中绑定 支付回调 → 支付 → id。
查询支付记录
添加 「数据库 - 获取数据」节点,查询支付表,条件为 id 等于 payment_id。
判断支付金额是否准确
添加 条件分支,判断 支付记录/总金额 等于 支付记录/order/{金额字段}。支付记录的总金额等于发起支付时的 道具单价 × 购买数量,币种固定为 CNY。
这一步非常重要。如果跳过,攻击者可以篡改支付金额,用远低于订单价格的金额完成支付,给你造成直接的经济损失。
更新订单并发放权益
在条件成立的分支中:
- 添加 数据库 节点修改订单表,把订单状态改为已支付。
- 按业务需要发放道具对应的权益,例如增加代币、解锁剧集或开通会员。
行为流的结构与微信支付相同,见微信支付(微信小程序)- 支付完成时。
退款成功时
退款有了结果后,退款记录变为 REFUNDED(退款成功)或 FAILED(退款失败),Zion 运行此行为流。退款成功和退款失败都会进入这个行为流,需要分别处理。
为行为流添加入参 refund_id(长整数),在输入配置中绑定 支付回调 → 退款 → id,然后查询退款记录,按状态分别处理。具体步骤见微信支付(微信小程序)- 退款成功时。
只有通过 Zion 的退款行为发起的退款会运行此行为流。在微信公众平台后台直接发起的退款,Zion 中没有对应的退款记录,不会运行此行为流。
iOS 订单的退款由支付者在自己手机的钱包中向苹果申请,Zion 收不到通知,也不会运行此行为流,见 iOS 支付限制。
配置前端支付行为
单次支付
添加创建订单行为
调用支付行为前,先在已绑定的订单表中创建订单。道具、金额和用户等业务数据应保存在订单表中。
添加支付行为
在按钮或其他组件的触发器中添加 支付,支付类型 选择 单次支付,支付配置 选择前面创建的微信虚拟支付配置,支付产品 选择 道具直购。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 订单表 id | 长整数 | 是 | 已绑定订单表中的订单记录 id |
| 道具 ID | 文本 | 是 | 在 道具配置 中添加的道具 id |
| 道具单价 | 小数 | 是 | 单位为元,最多两位小数,必须与道具配置中的价格一致,否则微信会拒绝下单。iOS 上最少 1 元 |
| 购买数量 | 整数 | 是 | 不小于 1 |

支付行为的 成功时 表示用户在小程序中完成了付款操作,最终支付状态仍以 支付完成时 为准。出于安全考虑,成功时 不能配置修改数据的行为。
处理支付完成
支付成功后,Zion 把支付记录更新为 SUCCESSFUL,并运行 支付完成时 绑定的行为流,在其中更新订单和发放权益。配置方法见支付完成时。
显示最终结果
前端查询订单表或支付表显示最终状态。需要及时刷新时,可以采用订阅查询的方法。
退款
开放退款权限
退款权限默认不开放。在支付配置的 权限管理 中,只为可信任的管理员角色勾选 退款。
确认小程序已授权退款权限
如果小程序是通过授权方式发布的,需要授权 虚拟支付退款 相关权限(权限集 157)。新授权的小程序默认包含此权限;更早授权的小程序如果退款时提示 退款失败,请联系商家开通虚拟支付退款权限,请在发布页面重新授权。
以私钥方式发布的小程序不需要这一步。
添加退款行为
添加 支付 行为,支付类型 选择 退款。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 支付表 id | 长整数 | 是 | 需要退款的支付记录 id,不是订单 id |
| 退款金额 | 小数 | 是 | 单位为元;超过剩余可退金额时,按剩余可退金额退款 |

可以用订单 id 作为过滤条件查询对应的支付记录,再绑定其 id。只有 SUCCESSFUL 或 PARTIALLY_REFUNDED 的支付记录可以退款。
处理退款结果
发起退款后,退款记录状态为 REFUNDING。微信通知退款结果后,Zion 把退款记录更新为 REFUNDED 或 FAILED,并运行 退款成功时 绑定的行为流。配置方法见退款成功时。
以上退款流程只适用于安卓订单。iOS 订单不能由开发者退款,通过退款行为发起会失败;支付者需要在自己手机的钱包中向苹果申请退款,退款后 Zion 收不到通知,不会运行 退款成功时 行为流。详见 iOS 支付限制。
测试与上线
- 沙箱测试:环境 选择 沙箱环境,使用 开发版本 中的道具,在安卓手机上测试付款流程。
- 上线:把道具发布到 线上版本,把 环境 切换为 正式环境,然后发布小程序。
- iOS 测试:上线后在 iPhone 上用正式环境实际付款测试,测试会产生真实扣款。
沙箱环境只能测试安卓。iOS 上的付款只能在正式环境中测试,见 iOS 支付限制。
常见问题
- 提示
15001,当前商户尚未开启 IOS 支付:在 虚拟支付 → 基本配置 → 基础配置 中开启 是否启用苹果 IAP 支付,等待大约 10 分钟生效。 - 提示
15011,payment_illegal_in_sandbox:苹果 IAP 不支持沙箱环境。把道具发布到线上版本,把支付配置的 环境 切换为 正式环境 后再测试。 - iOS 用户无法付款:苹果 IAP 只支持中国大陆地区的 Apple ID。
- 微信拒绝下单:检查 道具 ID 是否存在于当前环境对应的道具版本中,以及 道具单价 是否与道具配置中的价格一致。
- 保存消息推送配置时验证失败:确认支付配置已经同步到后端,Token 和 EncodingAESKey 与支付配置中的值完全一致,消息加密方式为明文模式、数据格式为 JSON。
- 用户已付款但订单没有更新:检查消息推送是否配置成功、支付配置的 环境 是否与付款时的环境一致、支付完成时 是否绑定了行为流,以及修改是否已经发布。
- 退款时提示
退款失败,请联系商家开通虚拟支付退款权限:在发布页面重新授权小程序,见确认小程序已授权退款权限。 - iOS 订单退款失败:iOS 订单不能由开发者退款,需要支付者在自己手机的钱包中向苹果申请。
- iOS 支付者在苹果退款后订单没有变化:苹果退款不会通知 Zion,订单和已发放的权益不会自动更新,需要按业务自行处理。