Stripe 支付

配置支付配置

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

填写商户信息

先绑定 Secret key，再点击 Endpoint secret 旁的 生成并绑定。Zion 会用 Secret key 在 Stripe 中创建一个指向本配置 通知地址 的 Webhook，并把签名密钥保存为 Secret。

更换 Secret key 或通知地址后，点击 重新生成并绑定。Zion 会删除 Stripe 中指向同一地址的旧 Webhook，再创建新的 Webhook。

选择支付产品和客户端

在 支付产品 中勾选 Element，并在 客户端管理 中勾选 Web 应用的客户端。

配置支付结果处理

在 支付结果处理 中为 支付完成时、退款成功时、订阅状态变更时 和 订阅续费时 各绑定一个行为流，具体步骤见下文的配置支付结果行为流。

配置权限

打开 权限管理，按角色勾选允许通过这个配置发起的支付类型：

也可以在 设置 → 权限 → 支付 中统一查看和修改。

添加入参

为行为流添加入参 payment_id（长整数），在支付配置中绑定 支付回调 → 支付 → id。

查询支付记录

添加 「数据库 - 获取数据」节点，查询支付表，条件为 id 等于 payment_id。

判断支付金额是否准确

由于实际支付的金额和订单记录中的金额可能不一致，需要判断金额准确后再做后续处理。

添加 条件分支，用以下条件判断金额是否准确：

• 支付记录/总金额 等于 支付记录/order/{金额字段}。
• 支付记录/币种 等于 支付记录/order/{币种字段}。

Stripe 的 总金额 以币种的最小单位保存，例如 10 美元保存为 1000。订单金额使用其他单位时，先换算再比较。

更新订单并发放权益

在条件成立的分支中：

1. 添加 数据库 节点修改订单表，把订单状态改为已支付。
2. 按业务需要发放权益，例如为对应的账户开通会员、增加积分，或发送通知。

添加入参

添加入参 refund_id（长整数），在输入配置中绑定 支付回调 → 退款 → id。

查询退款记录和订单

添加 「数据库 - 获取数据」节点，查询退款表，条件为 id 等于 refund_id。

按退款结果分别处理

添加 条件分支：

• 退款记录/状态 等于 REFUNDED：退款成功。在这个分支中再添加 条件分支，判断是全额退款还是部分退款：
  • 退款记录/金额 等于 退款记录/支付/总金额：全额退款，修改订单状态，并回收全部已发放的权益。
  • 其他情况：部分退款，按业务需要修改订单状态，并回收对应部分的权益。
• 退款记录/状态 等于 FAILED：退款失败。按业务需要通知管理员或用户，订单保持原状态。

添加入参

添加入参 recurring_payment_id（长整数），在输入配置中绑定 支付回调 → 周期性支付 → id。如需区分状态是从哪个状态变化而来，可以再添加一个文本入参，绑定 支付回调 → 变更前状态。

查询周期性支付记录

添加 「数据库 - 获取数据」节点，查询周期性支付表，条件为 id 等于 recurring_payment_id。

按订阅状态分别处理

添加 条件分支：

• 状态为 ACTIVE：为订阅账户开通或恢复订阅权益。
• 状态为 PAST_DUE 或 UNPAID：扣款未成功，按业务需要暂停权益或提醒用户。
• 状态为 CANCELED 或 INCOMPLETE_EXPIRED：订阅已终止，收回订阅权益。

在各分支中添加 数据库 节点更新数据时，可以用周期性支付记录中的字段作为过滤条件：

• 更新账户：条件为账户表的 id 等于 周期性支付记录/帐户id。
• 更新订单：条件为订单表的 id 等于 周期性支付记录/第一笔订单id。

用户取消订阅后，周期结束时取消 会先变为 true，此时订阅仍在当前周期内有效，可以按需提醒用户；周期结束后状态才会变为 CANCELED。

设置执行方式和出参

把行为流设为 同步执行，并添加一个长整数类型的出参，用来返回新订单的 id。

添加入参

添加入参 payment_id（长整数），在输入配置中绑定 支付回调 → 支付 → id。

查询支付和订单记录

• 添加 「数据库 - 获取数据」节点，查询支付表，条件为 id 等于 payment_id。
• 添加 「数据库 - 获取数据」节点，查询订单表，条件为 id 等于 支付记录/周期性支付/第一笔订单id，获取首期订单记录。

创建本期订单

添加 数据库 节点在订单表中新增一条订单，金额、账户和商品等字段使用上一步获取到的订单记录填写，订单状态设为待支付。

返回订单 id

把新订单的 id 赋给出参。Zion 会把它写回本期支付记录。

添加创建订单行为

调用支付行为前，先在已绑定的订单表中创建订单。订单金额、商品和用户等业务数据应保存在订单表中。

添加支付行为

在按钮或其他组件的触发器中添加 支付，支付类型 选择 单次支付，支付配置 选择前面创建的Stripe配置，支付产品 选择 Element。

不同币种有最低支付金额，详见 Stripe 文档 。

支付行为的 成功时 表示前端调用已成功返回，最终支付状态仍以 支付完成时 为准。出于安全考虑，成功时 不能配置修改数据的行为。

处理支付完成

支付成功后，Zion 把支付记录更新为 SUCCESSFUL，并运行 支付完成时 绑定的行为流，在其中更新订单和发放权益。配置方法见支付完成时。

显示最终结果

前端查询订单表或支付表显示最终状态。需要及时刷新时，可以采用订阅查询的方法。

开放退款权限

退款权限默认不开放。在支付配置的 权限管理 中，只为可信任的管理员角色勾选 退款。

添加退款行为

添加 支付 行为，支付类型 选择 退款。

可以用订单 id 作为过滤条件查询对应的支付记录，再绑定其 id。只有 SUCCESSFUL 或 PARTIALLY_REFUNDED 的支付记录可以退款。

处理退款结果

发起退款后，退款记录状态为 REFUNDING。Stripe 通知退款结果后，Zion 把退款记录更新为 REFUNDED 或 FAILED，并运行 退款成功时 绑定的行为流。Stripe 直接拒绝退款请求时，退款记录会变为 FAILED，退款行为进入 失败时。配置方法见退款成功时。

发起订阅

添加 支付 行为，支付类型 选择 周期支付，类型 选择 发起，支付配置 选择前面创建的 Stripe 配置，支付产品 选择 Element。

发起后，Zion 创建一条状态为 INCOMPLETE 的周期性支付记录和一条关联首期订单的支付记录。首期扣款成功时触发 支付完成时；订阅生效时触发 订阅状态变更时。前端分支只表示收银台交互结果，订阅是否生效以周期性支付记录的状态为准。

取消订阅

添加 支付 行为，支付类型 选择 周期支付，类型 选择 取消，并绑定需要取消的 周期支付表 id。

取消后订阅会在当前周期结束时终止：周期性支付记录的 周期结束时取消 立即变为 true，状态在周期结束时变为 CANCELED，此时触发 订阅状态变更时。