Skip to main content
Waffo 托管了一个页面，你的顾客可以在那里查看自己的订阅、管理 其上的支付方式并取消它。你从 /api/v1/subscription/manage 获取 URL 并把顾客送到那里。Waffo 发给 你顾客的邮件也可以链接到它——参见 发给你顾客的订阅邮件。

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

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

​
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 都会生成一个新的、独立的链接。 每个链接有自己的过期时间，响应会告诉你是什么： 值得围绕它设计的后果：
  • 生成新链接不会使较早的链接失效。 相隔几分钟发出的两个链接 在各自的 expiredAt 过去之前都有效。不要依赖 重新调用 manage 来撤销你已经发出的链接。
  • 读取 expiredAt；不要硬编码有效期。 窗口很短，而且是 配置而非契约。链接是一次交接，不是书签：在 顾客点击时生成它，而不是存一个之后再 邮寄。
  • 反复调用 manage 没问题——它对订阅 没有副作用。
Waffo 放在自己顾客邮件中的链接行为不同：它们持续 时间长得多，但每封新邮件带有一个新鲜度标记， 会取代较早邮件中的链接。所以顾客翻出上个 月的邮件可能发现那个链接已失效，而最新的邮件有效。这种 取代只在邮件链接之间发生；它永远不影响你 通过 API 生成的链接。

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

可以。Waffo 顾客邮件中的管理链接是指向 Waffo 的 托管页面还是你提供的 URL，是一个按账户的设置： 这就是 subscriptionManagementUrl 的用途，也是为什么该字段应该 指向顾客可以在桌面浏览器中打开的东西而不是 App deeplink。切换该设置需要向你的 Waffo 联系人提出请求，而不是 自助开关。 没有任何配置能把管理链接从邮件中完全 移除。如果你不想让 Waffo 的邮件把顾客引导到任何地方， 办法是关闭邮件本身并发送你自己的——参见 发给你顾客的订阅邮件。

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

看到——计划及其账单历史，比商户 查询 API 返回的更详细： 做——三件事： 支付方式规则以及为什么添加一个会创建零金额订单，在 订阅重试与支付方式。

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

不能。没有商户侧端点可以添加、替换、重排或 删除订阅上的支付方式。公开的订阅 API 是 create、inquiry、cancel、manage、change、change/inquiry 和 update——没有一个会触及已绑定的方式列表。 你可以从自己的产品中做的：
  • 从 /api/v1/subscription/inquiry 读取已绑定的方式和 canChangePaymentMethod 标志，并渲染你自己的视图。
  • 把顾客送到托管页面进行实际的变更。
  • 通过带不同 paymentInfo 的计划变更把顾客 转移到不同的支付方式，这会在收银台重新授权——参见 订阅计划变更。
所以可行的模式是：你的 UI 显示状态，托管页面执行 变更。

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

立即生效。 顾客确认后，订阅转为 USER_CANCELLED，不再开启新的账单周期。页面上没有 周期末取消的选项，/api/v1/subscription/cancel 也是立即 生效的。 这值得明确说出来，因为它是与商户自己产品规则 最常见的不匹配：Waffo 取消的是计费，而不是 权益。如果你的政策是”保留服务直到已付周期 结束”，你需要在自己这边实现：
  1. 监听订阅状态通知。
  2. 收到取消时，保留顾客的访问权直到他们已付周期 结束——该日期你可以在取消前从 nextPaymentDateTime 得知， 或从账单历史中当前周期的结束时间得知。
  3. 到那时撤销访问权。
Waffo 唯一执行周期末退役的地方是带未来 startTime 的计划 变更，它会让旧计划运行到其当前周期结束 后再退役。如果你的真实需求是”在周期末降级”， 那才是对应的机制——不是取消。

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

订阅转为 USER_CANCELLED，你会收到带该状态的订阅 状态通知。没有单独的”在托管页面上取消” 事件。 把该Webhook 通知视为触发器，而不是你自己的记录——这次取消不是你 发起的，所以在你处理该通知之前，你这边仍然认为 订阅是有效的。USER_CANCELLED 与 MERCHANT_CANCELLED 就是 你区分顾客发起的流失与你自己执行的取消的方式。 取消不会触及已经收取的款项。如果你想把当前周期 退给顾客，请退还该周期的扣款——参见 退款。

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

页面会采用订阅上配置的收银台外观和 logo ——与你用于收银台的 cashierAppearance 和品牌配置相同—— 所以颜色、字体和你的 logo 会延续过来，而不是让顾客 落到一个没有品牌的页面。 不可配置的： 所以如果你的需求是”顾客不得在这里取消”， 答案不是配置页面——而是不要把顾客送到那里，并 让 Waffo 的邮件指向你自己的管理 URL。

​
页面是什么语言？

与 Waffo 用于该订阅的收银台和邮件相同的解析方式：
  1. 你在订阅上设置的收银台语言（如果设置了）。
  2. 否则从订阅的扣款币种推导。
  3. 英语作为兜底。
语言在链接生成那一刻就固定在链接中，所以在你设置 收银台语言之前生成的链接会保留旧语言，直到你生成 新的。如果你顾客的语言与其账单币种不一致，请在订阅上 显式设置收银台语言，而不是依赖 推导。 计划标题和描述是你的字符串——页面渲染你在订阅上 发送的描述，所以它以你书写的语言出现， 与页面自身的区域设置无关。如果你本地化了计划 名称，请在创建订阅时发送本地化后的字符串。