微信支付(小程序端)
Zion 的小程序端当前只支持微信 JSAPI 支付。
激活支付
开始配置前,你需要对 Zion 的支付功能有一个基本的了解。原理及步骤请参考 支付功能概述,并按照其中的说明创建订单表并激活支付。
配置商户信息
1. 参考 教程 ,注册企业小程序(个人小程序无法用支付)
2. 参考 微信支付商户平台 注册商户号,注册后:
- 开通 JSAPI 支付
- 配置授权目录:
https://zion-app.functorz.com/ - 商户号关联小程序 AppId
- 获取商户号、APIv2 密钥
- 如需退款,获取 apiclient_cert.p12 文件,详见 微信支付规范
3. 在 Zion 填写相关信息
配置单次支付
添加支付行为

行为参数说明:
| 参数 | 说明 |
|---|---|
| 订单表Id | 整数,必须是绑定的订单表里某一行的Id(因此建议先添加订单,成功时调用支付行为)。 |
| 金额 | 小数,单位为元,小数点后不能超两位,且必须大于0.01。 |
| 商品介绍 | 文本,商品的描述。 |
配置支付完成后的业务逻辑
支付完成后会自动触发对应的行为流。行为流内置一个“解析支付结果”的代码块,会返回四个关键参数:
| 参数 | 说明 |
|---|---|
| orderId | 调用支付行为时填写的orderId,可以用它找到对应的订单记录,并更新其状态 |
| paymentFound | 用于判断是否找到对应的支付记录 |
| paymentStatus | 支付状态: SUCCESSFUL - 支付成功 FAILED - 支付失败 |
| alreadyProcessed | 一次支付可能会多次触发行为流。该参数用于避免重复执行,当其值为 false 时,表示为第一次触发;当为 true 时,表示重复触发。因此 paymentStatus 为 FAILED 且 alreadyProcessed 为 false 时,才表示支付失败。支付成功的判断同理。 |

在后续的条件分支中,可根据这四个参数判断支付状态,并执行相应业务逻辑。
-
第一个条件分支,用
paymentFound判断是否找到对应的支付记录- 如果值为
true,则表示找到,进入第二个条件分支 - 如果值为
false,则表示没有找到,一般不做处理。
- 如果值为
-
第二个条件分支,用
paymentStatus和alreadyProcessed判断支付状态,- 如果
paymentStatus值为SUCCESSFUL且alreadyProcessed为false,则表示支付成功,在这个分支中配置支付成功后的业务逻辑。 - 如果
paymentStatus值为FAILED且alreadyProcessed为false,则表示支付失败,在这个分支中配置支付失败后的业务逻辑。 - 如果以上条件都不满足,则表示
alreadyProcessed的值为 true,说明已处理过,一般无需在该分支中配置内容。
- 如果
为了安全起见,防止有人恶意利用假的订单信息进行支付或退款(让实际支付的金额远小于订单中的金额),建议添加第三个条件分支,用于检查实际的支付金额和订单中的金额是否相等。具体方法是用订单 Id 作为过滤条件,获取订单表数据和支付表数据,再进行比较。

获取支付结果
由于订单表/支付表/退款表的更新在自定义行为流中进行,且需一定时间,前端可通过订阅方式获取最新数据。例如调用支付行为后,页面可订阅支付表以实时接收支付状态变化。

配置退款
添加退款行为

行为参数说明:
| 参数 | 说明 |
|---|---|
| 支付表Id | 整数,可以用订单Id作为过滤条件,获取对应的支付表Id。 |
| 退款金额 | 小数,单位为元,小数点后不能超两位。同一笔支付可以发起多次退款,退款金额的总和不能超过支付的总金额。 |
配置退款行为的权限
退款行为默认对所有用户关闭权限。为了防止金钱上的损失,建议不要对普通用户开放,而是新建一个类似管理员的角色,给它开放退款权限。

配置退款完成后的业务逻辑
和支付类似,退款完成后会自动触发退款行为流。其内置的“解析退款结果”代码块会返回四个关键参数:
| 参数 | 说明 |
|---|---|
| orderId | 调用支付行为时填写的orderId,可以用它找到对应的订单记录,并更新其状态 |
| refundFound | 用于判断是否找到对应的退款记录 |
| paymentStatus | 支付状态: REFUNDED - 退款成功 FAILED - 退款失败 |
| alreadyProcessed | 一次退款可能会多次触发行为流,当其值为 false 时,表示为第一次触发;当为 true 时,表示重复触发。 |

在后续的条件分支中,可根据这四个参数判断退款状态:
- 用
refundFound判断是否找到对应的退款记录 - 用
paymentStatus和alreadyProcessed判断退款状态
由于逻辑和支付行为流类似,这里不再赘述。
获取退款结果
退款表仅默认开放基础查询权限,如需聚合数据(例如总数、求和等),请前往数据表的权限配置中开启。
由于订单表/支付表/退款表的更新在自定义行为流中进行,且需一定时间,前端可通过订阅方式获取最新数据。

配置权限
在权限系统中可以配置行为的权限。尤其是退款行为(权限默认关闭),建议对普通用户关闭,否则可能会造成金钱上的损失。更正确的做法是新建一个类似管理员的角色,给它开放退款权限。

注意事项
版本到期的处理
在专业版到期后,线上应用的支付请求会报错,且项目将无法发布。此时你可以:
-
续费专业版。续费后项目能够正常发布,线上支付恢复正常。
-
关闭支付。在支付设置面板中可以关闭支付,支付的配置、行为流会被清除;在部署后端后数据,支付、周期性支付、退款三张表中的数据也会被清除。支付关闭后,项目即可正常发布。
微信支付报错处理
- 调用支付行为报错:JSAPI缺少参数 total_fee
-
检查支付的参数是否正确(例如:确保金额有值且大于0.01)
-
前往商户号检查其状态是否正常
- 调用支付行为报错:JSAPI缺少参数 appId
-
检查商户号是否关联小程序或公众号
-
检查登录信息是否填写正确(appId 和 secret)