Skip to Content

微信支付(小程序端)

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,则表示没有找到,一般不做处理。
  • 第二个条件分支,用paymentStatusalreadyProcessed判断支付状态,

    • 如果paymentStatus值为SUCCESSFULalreadyProcessedfalse,则表示支付成功,在这个分支中配置支付成功后的业务逻辑。
    • 如果paymentStatus值为FAILEDalreadyProcessedfalse,则表示支付失败,在这个分支中配置支付失败后的业务逻辑。
    • 如果以上条件都不满足,则表示 alreadyProcessed 的值为 true,说明已处理过,一般无需在该分支中配置内容。

为了安全起见,防止有人恶意利用假的订单信息进行支付或退款(让实际支付的金额远小于订单中的金额),建议添加第三个条件分支,用于检查实际的支付金额和订单中的金额是否相等。具体方法是用订单 Id 作为过滤条件,获取订单表数据和支付表数据,再进行比较。

支付金额校验示意图

获取支付结果

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

支付结果获取示意图

配置退款

添加退款行为

微信退款行为

行为参数说明:

参数说明
支付表Id整数,可以用订单Id作为过滤条件,获取对应的支付表Id。
退款金额小数,单位为元,小数点后不能超两位。同一笔支付可以发起多次退款,退款金额的总和不能超过支付的总金额。

配置退款行为的权限

退款行为默认对所有用户关闭权限。为了防止金钱上的损失,建议不要对普通用户开放,而是新建一个类似管理员的角色,给它开放退款权限。

退款权限配置示意图

配置退款完成后的业务逻辑

和支付类似,退款完成后会自动触发退款行为流。其内置的“解析退款结果”代码块会返回四个关键参数:

参数说明
orderId调用支付行为时填写的orderId,可以用它找到对应的订单记录,并更新其状态
refundFound用于判断是否找到对应的退款记录
paymentStatus支付状态: REFUNDED - 退款成功 FAILED - 退款失败
alreadyProcessed一次退款可能会多次触发行为流,当其值为 false 时,表示为第一次触发;当为 true 时,表示重复触发。

退款处理示意图

在后续的条件分支中,可根据这四个参数判断退款状态:

  • refundFound 判断是否找到对应的退款记录
  • paymentStatusalreadyProcessed 判断退款状态

由于逻辑和支付行为流类似,这里不再赘述。

获取退款结果

退款表仅默认开放基础查询权限,如需聚合数据(例如总数、求和等),请前往数据表的权限配置中开启。

由于订单表/支付表/退款表的更新在自定义行为流中进行,且需一定时间,前端可通过订阅方式获取最新数据。

支付结果获取示意图

配置权限

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

权限配置示意图

注意事项

版本到期的处理

在专业版到期后,线上应用的支付请求会报错,且项目将无法发布。此时你可以:

  • 续费专业版。续费后项目能够正常发布,线上支付恢复正常。

  • 关闭支付。在支付设置面板中可以关闭支付,支付的配置、行为流会被清除;在部署后端后数据,支付、周期性支付、退款三张表中的数据也会被清除。支付关闭后,项目即可正常发布。

微信支付报错处理

  1. 调用支付行为报错:JSAPI缺少参数 total_fee
  • 检查支付的参数是否正确(例如:确保金额有值且大于0.01)

  • 前往商户号检查其状态是否正常

  1. 调用支付行为报错:JSAPI缺少参数 appId
  • 检查商户号是否关联小程序或公众号

  • 检查登录信息是否填写正确(appId 和 secret)

Last updated on