> ## 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.

# 托管的订阅管理页面

> /subscription/manage 如何工作：哪些状态会返回链接以及为什么会得到 A0028、链接有效多久以及新链接是否会使旧链接失效、顾客在页面上到底能看到和做什么、页面可以品牌化到什么程度，以及为什么在那里取消是立即生效的。

Waffo 托管了一个页面，你的顾客可以在那里查看自己的订阅、管理
其上的支付方式并取消它。你从
`/api/v1/subscription/manage` 获取 URL 并把顾客送到那里。Waffo 发给
你顾客的邮件也可以链接到它——参见
[发给你顾客的订阅邮件](/docs/zh/support/subscription-notifications-faq)。

## 我能为哪些订阅获取管理链接？

任何曾经真正作为生效订阅存在过的——包括已经
结束的：

| 订阅状态 | `/subscription/manage` |
| - | - |
| `ACTIVE` | 返回链接 |
| `MERCHANT_CANCELLED`、`USER_CANCELLED`、`CHANNEL_CANCELLED`、`PLATFORM_CANCELLED` | 返回链接 |
| `EXPIRED` | 返回链接 |
| `IN_PROGRESS` | 拒绝——`A0028` |
| `AUTHORIZATION_REQUIRED` | 拒绝——`A0028` |
| `CLOSE` | 拒绝——`A0028` |

## `A0028` 是什么意思？

> `A0028` — Subscription is still in progress or has failed and management url is
> not available

它表示订阅从未生效：顾客还没有完成
确认、还没有授权委托，或者订阅在激活之前
就关闭了。没有什么可管理的，所以不会生成链接。

它**不是**权限或配置错误，在状态不变的情况下重试
也没有用。应该做的是：

* `IN_PROGRESS` / `AUTHORIZATION_REQUIRED`——顾客还欠你一个
  授权。把他们送到创建响应中的 `subscriptionAction.webUrl`，
  而不是管理链接。
* `CLOSE`——订阅已死，无法复活。创建一个新的。

## 已取消或已过期的订阅还能打开吗？

可以，而且这是有意为之。顾客仍然可以看到计划和他们的
账单历史——这通常正是他们取消后想要的。

他们不能做的是对其进行操作：对任何非 `ACTIVE` 的订阅，
支付方式变更都会被拒绝，也没有什么可取消的了。所以
已终止订阅的页面是只读的收据，不是重新订阅的入口。
如果回头客想要恢复计划，那是通过 `/api/v1/subscription/create`
创建的新订阅。

## 链接有效多久，新链接会使旧链接失效吗？

每次调用 `/api/v1/subscription/manage` 都会生成一个**新的、独立的**链接。
每个链接有自己的过期时间，响应会告诉你是什么：

| 响应字段 | 用途 |
| - | - |
| `managementUrl` | 发给顾客的链接 |
| `expiredAt` | 该链接的过期时间，ISO 8601，UTC |
| `subscriptionStatus` | 链接生成那一刻订阅的状态 |

值得围绕它设计的后果：

* **生成新链接不会使较早的链接失效。** 相隔几分钟发出的两个链接
  在各自的 `expiredAt` 过去之前都有效。不要依赖
  重新调用 `manage` 来撤销你已经发出的链接。
* **读取 `expiredAt`；不要硬编码有效期。** 窗口很短，而且是
  配置而非契约。链接是一次交接，不是书签：在
  顾客点击时生成它，而不是存一个之后再
  邮寄。
* 反复调用 `manage` 没问题——它对订阅
  没有副作用。

Waffo 放在**自己**顾客邮件中的链接行为不同：它们持续
时间长得多，但每封新邮件带有一个新鲜度标记，
**会取代较早邮件中的链接**。所以顾客翻出上个
月的邮件可能发现那个链接已失效，而最新的邮件有效。这种
取代只在邮件链接之间发生；它永远不影响你
通过 API 生成的链接。

## Waffo 的邮件能改为指向我自己的管理页面吗？

可以。Waffo 顾客邮件中的管理链接是指向 **Waffo 的
托管页面**还是**你提供的 URL**，是一个按账户的设置：

| 设置 | 邮件链接到 |
| - | - |
| Waffo 的页面（默认） | 托管页面，带一个新生成的链接 |
| 你的页面 | 你在 `/subscription/create` 上发送的 `subscriptionManagementUrl` |

这就是 `subscriptionManagementUrl` 的用途，也是为什么该字段应该
指向顾客可以在桌面浏览器中打开的东西而不是 App
deeplink。切换该设置需要向你的 Waffo 联系人提出请求，而不是
自助开关。

没有任何配置能把管理链接从邮件中完全
移除。如果你不想让 Waffo 的邮件把顾客引导到任何地方，
办法是关闭邮件本身并发送你自己的——参见
[发给你顾客的订阅邮件](/docs/zh/support/subscription-notifications-faq)。

## 顾客在页面上到底能看到和做什么？

**看到**——计划及其账单历史，比商户
查询 API 返回的更详细：

| 页面上 | 说明 |
| - | - |
| 计划描述、金额和周期 | 按订阅上的配置 |
| 状态 | 订阅的当前状态 |
| 已绑定的支付方式 | 脱敏的卡信息及有效期（如适用） |
| 每期账单历史 | 期数、两组币种/金额对、期开始和结束、试用标记，以及失败期的面向顾客的失败原因 |
| 每期一个收据链接 | 仅在**以非零金额扣款成功**的期上存在——所以验证行和零金额行没有 |

**做**——三件事：

| 操作 | 可用性 |
| - | - |
| 取消订阅 | `ACTIVE` 期间 |
| 添加支付方式、设置不同的默认方式、重排备用方式、删除方式 | 卡、Apple Pay 和 Google Pay 订阅，`ACTIVE` 期间；当前默认方式不能删除 |
| 模拟下一次续订 | 仅沙箱——参见[沙箱测试](/docs/zh/support/sandbox-testing-faq) |

支付方式规则以及为什么添加一个会创建零金额订单，在
[订阅重试与支付方式](/docs/zh/support/subscription-retry-and-payment-methods-faq)。

## 我能改从自己的后端做支付方式管理吗？

不能。**没有商户侧端点**可以添加、替换、重排或
删除订阅上的支付方式。公开的订阅 API 是
`create`、`inquiry`、`cancel`、`manage`、`change`、`change/inquiry` 和
`update`——没有一个会触及已绑定的方式列表。

你可以从自己的产品中做的：

* 从 `/api/v1/subscription/inquiry` 读取已绑定的方式和
  `canChangePaymentMethod` 标志，并渲染你自己的视图。
* 把顾客送到托管页面进行实际的变更。
* 通过带不同 `paymentInfo` 的**计划变更**把顾客
  转移到不同的支付方式，这会在收银台重新授权——参见
  [订阅计划变更](/docs/zh/support/subscription-plan-change-faq)。

所以可行的模式是：你的 UI 显示状态，托管页面执行
变更。

## 页面上的取消是立即生效，还是在周期结束时？

**立即生效。** 顾客确认后，订阅转为
`USER_CANCELLED`，不再开启新的账单周期。页面上没有
周期末取消的选项，`/api/v1/subscription/cancel` 也是立即
生效的。

这值得明确说出来，因为它是与商户自己产品规则
最常见的不匹配：Waffo 取消的是**计费**，而不是
**权益**。如果你的政策是"保留服务直到已付周期
结束"，你需要在自己这边实现：

1. 监听订阅状态通知。
2. 收到取消时，保留顾客的访问权直到他们已付周期
   结束——该日期你可以在取消前从 `nextPaymentDateTime` 得知，
   或从账单历史中当前周期的结束时间得知。
3. 到那时撤销访问权。

Waffo 唯一执行周期末退役的地方是**带未来 `startTime` 的计划
变更**，它会让旧计划运行到其当前周期结束
后再退役。如果你的真实需求是"在周期末降级"，
那才是对应的机制——不是取消。

## 顾客在那里取消时我会收到什么状态变更和Webhook 通知？

订阅转为 `USER_CANCELLED`，你会收到带该状态的**订阅
状态通知**。没有单独的"在托管页面上取消"
事件。

把该Webhook 通知视为触发器，而不是你自己的记录——这次取消不是你
发起的，所以在你处理该通知之前，你这边仍然认为
订阅是有效的。`USER_CANCELLED` 与 `MERCHANT_CANCELLED` 就是
你区分顾客发起的流失与你自己执行的取消的方式。

取消不会触及已经收取的款项。如果你想把当前周期
退给顾客，请退还该周期的扣款——参见
[退款](/docs/zh/support/refund-faq)。

## 页面可以品牌化到什么程度？

页面会采用**订阅上配置的收银台外观和 logo**
——与你用于收银台的 `cashierAppearance` 和品牌配置相同——
所以颜色、字体和你的 logo 会延续过来，而不是让顾客
落到一个没有品牌的页面。

**不可**配置的：

| | |
| - | - |
| 颜色、背景、字体、logo | 从你的收银台外观应用 |
| 页面文案和标签 | 固定。商户不可编辑。 |
| 隐藏取消按钮或任何其他控件 | 不支持 |
| 添加你自己的字段或区块 | 不支持 |

所以如果你的需求是"顾客不得在这里取消"，
答案不是配置页面——而是不要把顾客送到那里，并
让 Waffo 的邮件指向你自己的管理 URL。

## 页面是什么语言？

与 Waffo 用于该订阅的收银台和邮件相同的解析方式：

1. 你在订阅上设置的收银台语言（如果设置了）。
2. 否则从订阅的扣款币种推导。
3. 英语作为兜底。

语言在链接生成那一刻就固定在链接中，所以在你设置
收银台语言之前生成的链接会保留旧语言，直到你生成
新的。如果你顾客的语言与其账单币种不一致，请在订阅上
显式设置收银台语言，而不是依赖
推导。

计划标题和描述是**你的**字符串——页面渲染你在订阅上
发送的描述，所以它以你书写的语言出现，
与页面自身的区域设置无关。如果你本地化了计划
名称，请在创建订阅时发送本地化后的字符串。


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