支付

Zion 支付能力支持通过内置支付行为完成收款、退款等操作，已支持微信小程序支付、微信 H5 支付、支付宝网页端一次性支付和周期订阅支付。

仅专业版及企业版用户可用。专业版到期将导致支付功能失效，请及时续费。

使用教程

第一步：配置支付所需基础信息

进入支付配置

绑定订单表并激活支付功能

需先创建订单表（建议包含价格、用户 ID 等字段），激活支付时选择该表。

• 微信支付和支付宝共用同一订单表
• 绑定后无法解绑或换绑，订单表无法删除（除非将支付关闭清除所有数据后，重新打开支付，重新绑定）

激活后系统自动完成：

• 创建三张表：支付表（1:N 订单）、周期性支付表、退款表（1:N 支付）
• 创建行为流：
  • 微信支付：支付回调、退款回调
  • 支付宝：支付/退款回调、周期性支付管理回调、周期性支付定时扣款

配置商户信息（微信支付）

注册微信商户号

教程：如何申请商户号 。注册后：

1. 开通 JSAPI 支付
2. 配置授权目录：https://zion-app.functorz.com/
3. 获取商户号、APIv2 密钥
4. 如需退款，获取 apiclient_cert.p12 文件，见微信支付规范 

在 Zion 填写商户号信息

• 小程序端配置

  1. 注册企业小程序（个人小程序无法用支付），参考注册流程 
  2. 商户号关联小程序 AppId
  3. 在 Zion 后台填写相关信息

  

• Web 端（微信 JSAPI 支付，仅限微信客户端内）配置

  1. 商户号授权目录设置为 Web 发布地址（自定义域名）

  2. Web 端需配置微信授权登录：

     • 准备公众号（服务号，已完成企业认证）

     • 关联服务号 AppId

     • 配置网页授权域名（自定义域名）

     • 上传校验文件至根目录

       

     • 授权完成后，配置登录方式（填写公众号 AppId 和 AppSecret）

       

  3. 完成上述步骤后，将商户信息填入 Zion（AppId 为公众号的 AppId）

  

配置商户信息（支付宝）

1. 注册商户号（支持电脑网站支付的方式）选择自研商家接入模式，链接：支付宝接入准备 
2. 在支付宝开放平台-控制台创建网页应用，配置应用的开发设置：
   • 接口加签方式：选择“密钥”。加签算法：选择 ”RSA2“。
   • 应用网关：https://zionbackend.functorz.com/callback/alipay，及支付宝网关地址，并获取信息，并填入支付配置

• AppId
• 应用私钥/支付宝公钥： 可以通过下载支付宝开放平台密钥工具生成，目前 Zion 仅支持 RSA2 加密协议的公私钥

第二步：使用支付行为

支付、退款、发起或取消周期支付，都遵循下图的流程。开发者只需要配置其中的绿色部分：

1. 在前端页面上使用行为：发起支付、退款或周期支付
2. 在对应的行为流中配置业务逻辑
3. 在前端页面上查询最终结果

一次性支付和退款

1. 使用支付/退款行为

   
   
   

   行为参数说明：

   行为类型	参数	说明
   支付	订单表Id	整数，必须是绑定的订单表里某一行的Id（因此建议先添加订单，成功时调用支付行为）。
   	金额	小数，单位为元，小数点后不能超两位，且必须大于0.01。
   	商品介绍（微信支付）	文本，商品的描述。
   	商品名称（支付宝）	文本，可以是商品的标题/交易标题/订单标题/订单关键字等。
   退款	支付表Id	整数，可以用订单Id作为过滤条件，获取对应的支付表Id。
   	退款金额	小数，单位为元，小数点后不能超两位。同一笔支付可以发起多次退款，退款金额的总和不能超过支付的总金额。

2. 配置支付或退款完成后的业务逻辑

   支付或退款完成后将自动触发对应的行为流，行为流内置了一个代码块对结果分析，并返回关键信息。开发者需要在后续的分支中，自行配置业务逻辑。

   参数	说明
   orderId	调用支付行为时填写的orderId，可以用它找到对应的订单记录，并更新其状态
   paymentStatus	支付状态： REDUNDED - 退款成功 REDUNDING - 退款中 FAILED - 退款失败
   callbackProgressed	一次支付可能会多次触发行为流。该参数用于避免重复执行，当其值为 false 时，表示为第一次触发；当为 true 时，表示重复触发。因此 paymentStatus 为 FAILED 且 callbackProgressed 为 false 时，才表示支付失败。支付成功的判断同理。

   

   为了安全起见，防止有人恶意利用假的订单信息进行支付或退款（让实际支付的金额远小于订单中的金额），在支付或退款成功后，建议检查实际的支付金额和订单中的金额是否相等。具体方法是用订单 Id 作为过滤条件，分别获取订单表数据和支付表数据，再进行条件判断。

   

3. 获取支付结果

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

   

周期支付

周期支付涉及到发起、取消、扣款几个步骤

1. 发起和取消

   
   
   

   类型	参数	说明
   发起	订单表Id	整数，必须是绑定的订单表里某一行的Id（因此建议先添加订单，成功时调用支付行为）。
   	价格	小数，单位是元，小数点后不超过两位。由于支付宝的限制，只能支持100元以内的周期支付
   	商品名称	文本
   	扣款间隔	整数，扣款间隔不能少于7天，无最大限制
   	场景	文本，只能填支付宝规定的场景值 （例如：INDUSTRY
   取消	周期支付表Id	整数，可以用用户Id作为过滤条件获取到对应的周期支付记录

2. 周期支付扣款

   通过定时触发扣款行为流，查询到需要扣款的周期支付，每个扣款，都需要创建一个新的订单

   

第三步：权限配置

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

注意事项

版本到期的处理

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

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

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

微信支付报错处理

1. 调用支付行为报错：JSAPI缺少参数 total_fee

• 检查支付的参数是否正确（例如：确保金额有值且大于0.01）

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

• 检查商户号是否关联小程序

支付宝报错处理

1. 发起支付宝周期支付，用户在支付宝端显示“商户协议状态不正常”

• 查看周期支付表中是否有同一个账户多次订阅的情况，由于支付宝限制一个用户只能用一个场景码订阅一次，因此如果有一个用户订阅多次的情况，请保证发起周期支付的行为中场景码不同

2. 退款成功后，回调行为流没有触发

• 由于支付宝的限制，如果是全额退款，不会触发行为流。