支付宝支付

Zion 当前只支持支付宝电脑网站支付方式的一次性支付、周期订阅支付。

激活支付

开始配置前，你需要对 Zion 的支付功能有一个基本的了解。原理及步骤请参考支付功能概述，并按照其中的说明创建订单表并激活支付。

配置商户信息

注册商户号

选择自研商家接入模式，详见：支付宝接入准备

配置应用

在支付宝开放平台-控制台创建网页应用，配置应用的开发设置：

接口加签方式选择”密钥”，算法选择 “RSA2”
应用网关：https://zionbackend.functorz.com/callback/alipay，及支付宝网关地址，并获取信息，并填入支付配置
应用私钥/支付宝公钥：可通过下载支付宝开放平台密钥工具生成，目前 Zion 仅支持 RSA2 加密协议的公私钥

使用支付行为

支付行为包括单次支付、周期支付和退款。为了更好地配置出支付，开发者需要知道一次支付完整的运行流程。

所有支付行为都遵循下图的流程。在 Zion 中，开发者只需要配置其中的绿色部分：

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

配置单次支付

添加支付行为

行为参数说明：

参数	说明
订单表Id	整数，必须是绑定的订单表里某一行的Id（因此建议先添加订单，成功时调用支付行为）。
金额	小数，单位为元，小数点后不能超两位，且必须大于0.01。
商品名称	文本，可以是商品的标题/交易标题/订单标题/订单关键字等。

配置支付完成后的业务逻辑

支付完成后会自动触发对应的行为流。行为流内置一个“解析支付结果”的代码块，会返回四个关键参数：

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

支付处理示意图

在后续的条件分支中，可根据这四个参数判断支付状态，并执行相应业务逻辑。

第一个条件分支，用paymentFound判断是否找到对应的支付记录
- 如果值为true，则表示找到，进入第二个条件分支
- 如果值为false，则表示没有找到，一般不做处理。
第二个条件分支，用paymentStatus和alreadyProcessed判断支付状态，
- 如果paymentStatus值为SUCCESSFUL且alreadyProcessed为false，则表示支付成功，在这个分支中配置支付成功后的业务逻辑。
- 如果paymentStatus值为FAILED且alreadyProcessed为false，则表示支付失败，在这个分支中配置支付失败后的业务逻辑。
- 如果以上条件都不满足，则表示 alreadyProcessed 的值为 true，说明已处理过，一般无需在该分支中配置内容。

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

支付金额校验示意图

获取支付结果

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

配置退款

添加退款行为

行为参数说明：

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

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

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

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

退款处理示意图

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

用 refundFound 判断是否找到对应的退款记录
用 paymentStatus 和 alreadyProcessed 判断退款状态

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

获取退款结果

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

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

配置周期支付

周期支付用于订阅服务、分期付款等需要定期自动扣款的场景。周期支付涉及到发起、取消、和自动扣款几个步骤。

发起和取消

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

周期支付扣款

支付宝周期支付的扣款通过定时触发（每天一次）扣款行为流实现。在该行为流中，会查询到需要扣款的所有周期支付，然后用循环对每一笔周期支付进行扣款。

每次扣款都需创建一个新的订单，因此需要开发者：

在循环中自主添加创建订单的行为
在扣款代码块中，将创建的订单的 id 绑定到代码块的入参 orderId

周期支付扣款示意图

配置权限

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

权限配置示意图

注意事项

版本到期的处理

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

续费专业版。续费后项目能够正常发布，线上支付恢复正常。
关闭支付。在支付设置面板中可以关闭支付，支付的配置、行为流会被清除；在部署后端后数据，支付、周期性支付、退款三张表中的数据也会被清除。支付关闭后，项目即可正常发布。

支付宝报错处理

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

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

退款成功后，支付行为流没有触发

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