Airwallex 支付配置指南

进入控制台

Airwallex 有沙盒环境 和生产环境 两种，请先登录进入对应的控制台。

创建 API 密钥

在控制台中，点击 Settings -> Developers -> API Keys，创建新的 API 密钥。

获取 API 密钥和客户端标识

创建 API 密钥后，系统会自动生成客户端标识。API 密钥仅在创建时可见，若遗忘请点击 Regenerate 重新生成。

配置法定实体标识和关联支付账户标识

在控制台中，点击 Settings -> Entities，创建新的法定实体。

创建 Webhooks

在控制台中，点击 Settings -> Webhooks，点击 New Webhook。

配置 Webhooks

API 版本请直接填入固定值 2025-11-11。

账户选中支付配置中关联支付账户标识对应的账户。

勾选以下事件：

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

通知地址填 Zion 中 Airwallex 支付处理行为流的 Webhook 地址。获取路径如下： 在 Zion 编辑器顶部导航栏点击行为，在左侧边栏找到系统自动生成的 Airwallex 支付处理行为流，点击顶部的触发器节点，复制右侧面板中的 Webhook 地址。

点击 Create，复制下图中的 Webhook 密钥。

将参数填入 Zion 的支付配置中

添加单次支付行为

在 Zion 前端页面按钮的点击时事件中，添加 Airwallex 支付行为，支付类型选择单次支付。

行为参数说明：

配置 Airwallex 支付处理行为流

当用户完成或取消单次支付时，系统自动生成的 Airwallex 支付处理行为流会自动触发。其处理逻辑如下：

1. 判断支付类型：解析事件类型代码块节点会解析出事件类型为 payment_intent.succeeded（成功支付） 或 payment_intent.cancelled（取消支付），进入支付状态变更分支。
2. 同步支付状态：通过同步支付状态节点自动查询支付记录，将其状态更新为成功或取消，并记录是否已处理标识，防止因网络重试导致的回调重复触发。此节点会输出 5 个参数：

3. 判断是否找到支付记录：通过判断支付标识是否为空，确认是否找到支付记录。若为空，则表示未找到，一般不做处理；若不为空，则进入下一分支。
4. 判断支付状态：通过判断支付状态 and 是否已处理的值，确认最终支付状态。
   • 若支付状态为 SUCCESSFUL 且是否已处理为 false，则表示支付成功，进入“成功”分支。
   • 否则，表示支付失败或取消，进入“其他”分支。
5. 自定义业务逻辑配置：在成功分支中配置支付成功后的业务逻辑，例如通过更新数据行为将订单状态修改为已支付。

添加退款行为

在 Zion 页面中，添加 Airwallex 支付行为。支付类型选择退款。

行为参数说明：

配置退款成功与失败的回调处理

当退款成功或失败时，Airwallex 支付处理行为流会自动触发。其处理逻辑如下：

1. 判断退款类型：解析事件类型代码块节点会解析出事件类型为 refund.accepted 或 refund.failed，进入退款状态变更分支。
2. 同步退款状态：通过同步退款状态节点自动查询退款记录，将其状态更新为成功或失败，并记录是否已处理标识。此节点会输出 6 个参数：

3. 判断是否找到退款记录：通过判断退款标识是否为空，确认是否找到退款记录。若为空，则表示未找到，一般不做处理；若不为空，则进入下一分支。
4. 判断退款状态：通过判断状态和是否已处理的值，确认最终退款状态。
   • 若状态为 REFUNDED 且是否已处理为 false，则表示退款成功，进入成功分支。
   • 若状态为 FAILED 且是否已处理为 false，则表示退款失败，进入失败分支。
   • 否则，表示其他情况，一般不做处理。
5. 自定义业务逻辑配置：在成功和失败分支中配置退款成功或失败后的业务逻辑，例如更新订单状态为已退款。

在 Airwallex 控制台创建产品与价格

在发起周期支付前，必须先在 Airwallex 中配置好对应的产品和价格计划。

1. 登录 Airwallex 控制台，点击左侧菜单的 Billing -> Products。
2. 点击 Create Product，填写产品名称和描述。
3. 在产品的 Pricing 模块中，点击 Add Price。
4. 计费模式选择 Recurring (周期性)，设置金额和扣款周期 (如每月、每年)。
5. 保存后，在价格列表中复制生成的 price ID，后续在 Zion 中发起订阅时需要用到此标识。

添加周期支付行为

在 Zion 页面中，添加 Airwallex 支付行为。支付类型选择周期支付。

行为参数说明：

执行机制：

• 执行行为时，系统会在后端准备订阅数据，并弹出收银台供用户授权绑卡及周期扣款。
• 授权成功或失败将触发前端的相应分支，但订阅的实际激活确认必须通过后端 Webhook 来处理。

处理周期支付的状态变化

当用户的周期支付发生试用、生效、欠费、续费、取消等状态变更时，Airwallex 支付处理行为流会自动触发。其处理逻辑如下：

1. 判断订阅状态：解析事件类型代码块节点会解析出事件类型为其中的一种：subscription.in_trial (试用期)、subscription.active (生效)、subscription.unpaid (欠费)、subscription.cancelled (取消) 或 subscription.modified (修改)，进入订阅状态变更分支。
2. 同步订阅状态：通过分支内的第一个节点同步订阅状态节点自动查询订阅记录，将其状态更新为试用期、生效、欠费、取消或修改。此节点会输出 2 个参数：

3. 判断是否找到订阅记录：通过判断周期支付标识是否为空，确认是否找到订阅记录。若为空，则表示未找到，一般不做处理；若不为空，则进入下一分支。
4. 判断订阅状态：通过判断 status 的值，确认最终订阅状态。
   • 若 status 为 ACTIVE，则表示生效，进入生效分支。
   • 若 status 为 CANCELLED，则表示取消，进入取消分支。
   • 否则，表示其他情况，一般不做处理。如果开发者有处理其他状态的需求，可自行添加相应的分支。

处理周期支付的扣款

当接收到自动续费通知时，Airwallex 支付处理行为流会自动触发。其处理逻辑如下：

1. 判断是否为周期支付：若事件类型为 invoice.finalized，则表示为周期支付，进入订阅续费分支。
2. 解析发票标识：通过解析发票标识节点自动解析出发票标识。
3. 处理订阅续费：通过处理订阅续费节点调用 Airwallex 订阅续费处理行为流，并将解析出的发票标识作为入参传递进去。

Airwallex 订阅续费处理行为流的处理逻辑：

1. 判断是否为自动续费：通过判断行为流输入参数发票标识是否为空来确认是否为自动续费。若非空，进入发票标识非空分支。
2. 获取或创建续费支付记录：内置自定义代码节点会根据发票标识自动生成或获取当期续费支付记录的支付标识，并同时返回该订阅对应的周期支付标识和首笔关联订单的首笔订单标识。
3. 判断是否找到订阅记录：通过判断周期支付标识是否非空，确认该次续费具有有效的订阅记录，进入找到订阅记录分支。
4. 获取支付记录：通过查询记录节点，利用上一步输出的支付标识查询当期续费支付记录的详细数据。
5. 检查订单标识是否存在：判断该支付记录是否已关联订单 (即订单标识为空)。若为空，说明尚未生成对应新订单，进入创建订单并关联支付分支；否则进入已关联，跳过分支，避免重复创建订单。
6. 获取首笔订单：系统利用前面获取到的首笔订单标识，查询用户首次订阅时创建的原始订单数据。
7. 创建订单 (需手动配置)：在系统自动生成的模板中找到用于创建订单的新增数据节点。开发者必须手动配置字段赋值，将获取首笔订单节点中查出的业务数据赋给新订单。例如，将新订单的订单金额绑定为 获取首笔订单.订单金额，用户标识绑定为 获取首笔订单.用户标识。
8. 更新支付记录中的订单标识：内置自定义代码节点会自动将新创建的订单标识，更新至当期续费的支付记录，从而完成新订单与本次续费扣款的绑定。