> ## 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 发给
你顾客的邮件也可以链接到它——参见
[发给你顾客的订阅邮件](https://waffo.com/docs/zh/support/subscription-notifications-faq.md)。

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

订阅仍在进行中或已失败时，管理链接不可用，接口返回 `A0028`；其他状态下能否获取链接，请以实际调用返回为准。

## `A0028` 是什么意思？

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

按接口规范，它表示订阅仍在进行中或已失败，没有可用的管理链接，所以不会生成链接。

遇到时请先用订阅查询确认订阅状态，不要对同一状态的订阅反复重试。若状态为 `AUTHORIZATION_REQUIRED`，请按创建响应中的 `subscriptionAction` 引导顾客完成授权，而不是索取管理链接。

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

是否仍可打开、能看到什么，以实际页面表现为准（见上一问关于管理链接可用状态的说明）。

更换支付方式只对未终止的订阅开放（状态不在 USER\_CANCELLED / MERCHANT\_CANCELLED / CHANNEL\_CANCELLED / EXPIRED / CLOSE，且支付方式为卡、Apple Pay、Google Pay）。要恢复计划，请通过 `/api/v1/subscription/create` 创建新订阅。

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

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

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

值得围绕它设计的后果：

* **每次调用都会生成独立的链接。** 每个链接有自己的 `expiredAt`；文档未说明新链接是否使较早链接失效，请不要依赖重新调用 `manage` 来撤销已发出的链接。
* **读取 `expiredAt`；不要硬编码有效期。** 管理链接有固定过期时间，接口返回 `expiredAt`。链接是一次交接，不是书签：在顾客点击时生成它，而不是存一个之后再邮寄。
* 反复调用 `manage` 没问题——它对订阅
  没有副作用。

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

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

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

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

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

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

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

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

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

**做**——三件事：

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

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

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

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

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

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

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

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

**取决于你选的取消方式。** 托管页的取消弹窗最多提供「立即」「本期结束」「自定义日期」三种选择；预约取消需账户开通，未开通或不支持的订阅只有立即取消。立即取消后订阅不可恢复。商户 `/api/v1/subscription/cancel` 的 `scheduledCancelAt` 为可选，留空为立即取消，填写则为预约取消：预约期间订阅状态保持 `ACTIVE`、权益照常，生效前可用 `/api/v1/subscription/resume` 撤销。完整规则见[预约取消与恢复订阅](https://waffo.com/docs/zh/support/subscription-scheduled-cancellation-and-resume-faq.md)。

权益由你自己的系统控制。如果你的政策是"保留服务直到已付周期结束"，可优先使用预约取消（周期结束时取消），或自己在这边实现：

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

如果你的真实需求是"在周期末降级"，请参见订阅套餐的升级与降级中关于变更开始时间的说明；它不是取消。

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

顾客立即取消时，订阅转为 `USER_CANCELLED`，你会收到带该状态的**订阅
状态通知**。没有单独的"在托管页面上取消"
事件。顾客选择预约取消时，订阅在生效前保持 `ACTIVE`，你收到的是预约取消通知 `SUBSCRIPTION_CANCELLATION_SCHEDULE_NOTIFICATION`，不是订阅状态通知；到点真正取消时才转为 `USER_CANCELLED` 并推送订阅状态通知。

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

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

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

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

**不可**配置的：

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

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

## 页面是什么语言？

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

1. 商户在订阅上指定的收银台语言 `cashierLanguage`（如果设置了）。
2. 否则按浏览器语言、用户所在国家 / IP 推断（收银台通用规则；订阅管理页是否完全一致请向集成支持确认）。
3. 英语作为兜底。

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

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


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