Skip to Content
帮助文档行为配置操作指南配置支付微信虚拟支付(微信小程序)

微信虚拟支付(微信小程序)

微信虚拟支付是微信为小程序内的虚拟商品提供的收款方式,例如短剧、会员、代币、课程等。用户在小程序里购买的是你在微信后台 虚拟支付 → 基本配置 → 道具配置 中添加的道具,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 分钟生效。

在虚拟支付基础配置中获取 AppID、OfferID 和 AppKey,并开启苹果 IAP 支付

添加道具

在 虚拟支付 → 基本配置 → 道具配置 中添加道具,记下每个道具的 道具 id 和 价格,后面发起支付时要用到。

  • 开发版本 中的道具可以在沙箱环境中测试。
  • 测试无误后把道具发布到 线上版本,正式环境只能购买线上版本中的道具。
  • 需要卖给 iOS 用户的道具,价格不能低于 1 元,见 iOS 支付限制。

在道具配置的线上版本中查看已发布的道具 id 和价格

支付配置

新建支付配置

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

新建支付,支付渠道选择微信虚拟支付

填写商户信息

商户信息中的值分两类:

  • 从微信获取: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。

⚠️

这一步非常重要。如果跳过,攻击者可以篡改支付金额,用远低于订单价格的金额完成支付,给你造成直接的经济损失。

更新订单并发放权益

在条件成立的分支中:

  1. 添加 数据库 节点修改订单表,把订单状态改为已支付。
  2. 按业务需要发放道具对应的权益,例如增加代币、解锁剧集或开通会员。

行为流的结构与微信支付相同,见微信支付(微信小程序)- 支付完成时。

退款成功时

退款有了结果后,退款记录变为 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 支付限制。

测试与上线

  1. 沙箱测试:环境 选择 沙箱环境,使用 开发版本 中的道具,在安卓手机上测试付款流程。
  2. 上线:把道具发布到 线上版本,把 环境 切换为 正式环境,然后发布小程序。
  3. iOS 测试:上线后在 iPhone 上用正式环境实际付款测试,测试会产生真实扣款。
⚠️

沙箱环境只能测试安卓。iOS 上的付款只能在正式环境中测试,见 iOS 支付限制。

常见问题

  1. 提示 15001,当前商户尚未开启 IOS 支付:在 虚拟支付 → 基本配置 → 基础配置 中开启 是否启用苹果 IAP 支付,等待大约 10 分钟生效。
  2. 提示 15011,payment_illegal_in_sandbox:苹果 IAP 不支持沙箱环境。把道具发布到线上版本,把支付配置的 环境 切换为 正式环境 后再测试。
  3. iOS 用户无法付款:苹果 IAP 只支持中国大陆地区的 Apple ID。
  4. 微信拒绝下单:检查 道具 ID 是否存在于当前环境对应的道具版本中,以及 道具单价 是否与道具配置中的价格一致。
  5. 保存消息推送配置时验证失败:确认支付配置已经同步到后端,Token 和 EncodingAESKey 与支付配置中的值完全一致,消息加密方式为明文模式、数据格式为 JSON。
  6. 用户已付款但订单没有更新:检查消息推送是否配置成功、支付配置的 环境 是否与付款时的环境一致、支付完成时 是否绑定了行为流,以及修改是否已经发布。
  7. 退款时提示 退款失败,请联系商家开通虚拟支付退款权限:在发布页面重新授权小程序,见确认小程序已授权退款权限。
  8. iOS 订单退款失败:iOS 订单不能由开发者退款,需要支付者在自己手机的钱包中向苹果申请。
  9. iOS 支付者在苹果退款后订单没有变化:苹果退款不会通知 Zion,订单和已发放的权益不会自动更新,需要按业务自行处理。
Last updated on