> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 订阅加座与补差扣款

> 说明订阅中途加座时如何只收当期差价：update 接口的 topupInfo、补差订单的支付与生效规则、如何确认补差成功、查询与 Portal 展示，以及加座失败时的处理。

本页讲订阅进行到一半、用户要增购（比如加几个席位）时，怎么只收当期差价、之后的周期怎么涨价，以及怎么确认这笔补差扣款成功了。字段级契约见官网 API 参考（`/api/v1/subscription/update`、`/api/v1/subscription/inquiry`）。

## 用户中途加座位，怎么只收差价？

调用 `/api/v1/subscription/update`，在请求里带上 `topupInfo`。一次请求同时做两件事：

* 立即创建一笔**当期补差订单**，收取 `topupAmount`；
* 补差成功后，从**下一期**起把周期金额调整为请求里的新 `amount`。

| 字段 | 说明 |
| - | - |
| `subscriptionId` 或 `subscriptionRequest` | 二选一，指明要更新的订阅。 |
| `amount`（或 `productInfo`） | 从下一期起的新金额。带 `topupInfo` 时也要带上目标金额。 |
| `topupInfo.topupRequest` | 这次加座的幂等键，长度不超过 32，只能用字母、数字、连字符。每次加座用一个新值，重试同一次请求时复用。 |
| `topupInfo.topupAmount` | 当期要补收的差额，**由你计算**，必须大于 0。Waffo 不替你按比例折算。 |
| `topupInfo.description` | 补差订单的描述，会显示在收银台和账单上。 |
| `topupInfo.orderExpiredAt` | 补差订单的有效期（收银台会话截止时间，ISO 8601）。不传则用默认时长。 |

示例：当前周期加 3 个席位，当期补 15，之后每期涨到 130。

```json theme={null}
{
  "subscriptionId": "SUB20260920000001",
  "amount": "130.00",
  "topupInfo": {
    "topupRequest": "seat-topup-001",
    "topupAmount": "15.00",
    "description": "Add three seats for the current period"
  }
}
```

不带 `topupInfo` 时，`update` 只是调整未来周期的金额，不会产生补差订单。

## 补差扣款需要用户再付一次吗？

要看支付方式和授权状态。响应里的 `topupInfo` 告诉你结果：

| 响应字段 | 说明 |
| - | - |
| `topupInfo.acquiringOrderId` | 补差订单的 Waffo 订单号，用来查支付结果。 |
| `topupInfo.topupStatus` | 补差订单当前状态。 |
| `topupInfo.topupAction` | 需要用户操作时返回，是一个 **JSON 字符串**。 |

当 `topupStatus` 是 `AUTHORIZATION_REQUIRED` 时，先把 `topupAction` 按 JSON 解析，再把用户重定向到其中的 `webUrl` 完成支付。不要把它当对象直接读属性。

## 补差扣款成功之前，之后的金额会变吗？

不会。新的 `amount` 只在补差订单**支付成功之后**才从下一期起生效；补差订单关闭或失败，后续周期的金额保持不变。

补差订单是当期内的额外订单，**不是新的一期**：

* 不开启新的计费周期，归属于受理时所在的当期；
* 加座处理期间，同一订阅上的取消、升降级等操作与它互斥；
* 订阅已有预约取消时，不能加座（返回 `A0058`），需先恢复订阅，见[预约取消与恢复订阅](https://waffo.com/docs/zh/support/subscription-scheduled-cancellation-and-resume-faq.md)。

`update` 本身只支持处于 `ACTIVE` 状态、由 Waffo 托管续订的订阅。

## 怎么确认补差扣款成功了？

不要把浏览器跳回你的页面当成付款成功。以下面两种为准：

1. **支付订单通知**：Waffo 向你的 `notifyURL` 推送 `PAYMENT_NOTIFICATION`，其中 `result.subscriptionInfo.subscriptionEvent` 为 `TOPUP_CHARGE`。
2. **主动查询**：如果通知延迟或丢失，用 `/api/v1/order/inquiry`，传补差订单的 `acquiringOrderId`。

收到 `TOPUP_CHARGE` 时请单独处理：它不是新一期的扣款，不要据此发放新一期的权益；新一期的权益仍以每期结果通知（`SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION`）为准。三类 `subscriptionEvent` 的区别见[跨币种订阅与 Portal FAQ](https://waffo.com/docs/zh/support/subscription-cross-currency-and-portal-faq.md) 和官网 [Webhook 事件类型](https://waffo.com/docs/zh/developer-docs/webhook/event-types.md)页。

## 怎么查某一期里有过哪些补差订单？

调用 `/api/v1/subscription/inquiry` 并把 `paymentDetails` 设为 `1`。每一期的扣款记录里，如果该期有过加座，会多一个 `topupDetails` 列表；没有加座时没有这个字段。

| `topupDetails` 里的字段 | 说明 |
| - | - |
| `acquiringOrderId` | 补差订单的 Waffo 订单号。 |
| `topupRequest` | 你传的加座幂等键。 |
| `topupAmount` | 该次补差金额。 |
| `orderCurrency` | 补差订单币种。 |
| `orderStatus` | 补差订单状态。 |

对账时请把 `topupDetails` 里的金额和该期正常扣款分开统计。

## 在商户 Portal 里怎么看补差订单？

在 Subscription → Agreements 的订阅详情页，Payment history 表格里会把补差订单和正常期单放在同一张表中展示：每期的补差订单显示在该期期单行的上方，Period No. 列显示为 “\{期号}-\{序号}”（例如 2-1、2-2），序号按受理时间从早到晚编号，同一期内最新的补差排在最上面；补差行不属于任何一期的试用或周期，所以 Trial 等周期相关列显示 “-”。

如果要对账，仍然建议把补差行的金额和该期正常扣款分开统计，和 API 的 topupDetails 一致。

## 加座失败了，订阅会怎样？

补差订单关闭或失败时，后续周期的金额不会改变，仍按原 `amount` 扣款。`topupRequest` 是这次加座的幂等键：重试同一次请求时复用同一个值。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.