Airwallex 支付

配置支付配置

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

在配置面板的 支付结果处理 中复制 通知地址，下一步会用到。

创建 Airwallex Webhook

在 Airwallex 控制台打开 Settings → Webhooks，创建 Webhook：

• API version：固定填写 2025-11-11。
• Account：选择 Linked payment account ID 对应的账户；未使用关联支付账户时选择当前收款账户。
• Notification URL：填写支付配置中显示的 通知地址。
• Events：勾选以下事件。

payment_intent.succeeded
payment_intent.cancelled
invoice.finalized
subscription.in_trial
subscription.active
subscription.unpaid
subscription.cancelled
subscription.modified
refund.accepted
refund.failed

创建后复制 Webhook secret。

填写商户信息

环境 必须与 Client ID、API key 和 Webhook 所在的 Airwallex 环境一致。测试环境和生产环境可以分别建一个支付配置。

选择支付产品和客户端

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

配置支付结果处理

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

配置权限

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

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

添加入参

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

查询支付记录

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

判断支付金额是否准确

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

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

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

Airwallex 的 总金额 以主货币单位保存，例如 10 美元保存为 10。

更新订单并发放权益

在条件成立的分支中：

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

添加入参

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

查询退款记录和订单

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

按退款结果分别处理

添加 条件分支：

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

添加入参

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

查询周期性支付记录

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

Airwallex 的订阅状态按下表保存到周期性支付记录：

按订阅状态分别处理

添加 条件分支：

• 状态为 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 会把它写回本期支付记录。

添加创建订单行为

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

添加支付行为

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

建议用户点击后立即禁用支付按钮，直到支付行为返回或收银台关闭，避免重复拉起收银台。

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

处理支付完成

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

显示最终结果

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

开放退款权限

Airwallex 退款只能由付款账户本人发起，其他账户发起退款会失败。在支付配置的 权限管理 中为付款用户所在的角色勾选 退款，并在业务上控制何时显示退款入口，例如只在订单满足退款条件时显示。

添加退款行为

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

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

处理退款结果

发起退款后，退款记录状态为 REFUNDING。Airwallex 发送 refund.accepted 或 refund.failed 后，Zion 把退款记录更新为 REFUNDED 或 FAILED，并运行 退款成功时 绑定的行为流。配置方法见退款成功时。

发起订阅

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

用户在收银台绑定支付方式后，Zion 创建自动扣款的订阅，以及状态为 INCOMPLETE 的周期性支付记录和关联首期订单的支付记录。前端分支只表示订阅授权交互结果，订阅是否生效以周期性支付记录的状态为准。

取消订阅

添加 支付 行为，支付类型 选择 周期支付，类型 选择 取消，并绑定需要取消的 周期支付表 id。只有订阅账户本人可以取消订阅。

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