API 参考：订阅

周期性扣款——相对 Crypto Bot 的扩展。您建一个套餐（金额 + 周期），把它的授权链接发给 用户，之后平台每一期从他们的钱包余额里扣款，扣掉手续费之后给您的应用余额入账。通用约定见 商户 API 参考页面。

模型

套餐是一份不可变的快照：用户授权的那一份，就是这个金额、这个周期。要改价格，就建一个 新套餐并把旧的归档——现有订阅者仍然按他们授权过的条件续费。第一期在授权时扣。

续费在每期结束时自动扣。续费失败（余额不足、账号受限）时，订阅进入 grace，平台在宽限期内 每小时重试一次（目前是 48 小时）；仍然扣不上的话，订阅变成 expired。商户拿 current_period_end 当准入截止时间来读。

生命周期里的每一个事件都有一个可订阅的 webhook：subscription_activated、 subscription_charged、subscription_cancelled、subscription_expired。

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan——权限范围 subscriptions。

参数	类型	必填	含义
name	string	是	1–64 个字符，显示给订阅者
asset	string	是	币种代码
amount	string	是	每期扣款额，正的小数字符串
period_days	integer	是	扣款周期天数，从平台最小值（目前是 7）到 365

返回的是套餐对象：plan_id、name、asset、amount、amount_minor、period_days、 archived、mini_app_subscribe_url——您发给用户去授权的那条 t.me 链接——以及 created_at。

错误：404 unknown_asset、400 invalid_amount、409 invalid_period、503 subs_disabled （该功能在平台侧被关掉了）。

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans——权限范围 read，无参数。返回 {"items": [plan, …]}，按时间倒序，每一项多带一个字段：active_subscribers——该套餐上仍然 有效的（active + grace）订阅数。

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan——权限范围 subscriptions。一个参数：plan_id。 它阻止的是新的授权；现有订阅照样按各自的快照续费（要逐个终止，请用 cancelSubscription）。归档没法通过 API 撤销。返回的是更新后的套餐对象，archived: true。 错误：404 plan_not_found。

getSubscriptions

GET /pay/api/getSubscriptions——权限范围 read。过滤条件：plan_id、user_id、status （active / grace / cancelled / expired），外加 offset / count（最大 500）。 返回 {"items": [subscription, …]}，按时间倒序。

订阅对象：subscription_id、plan_id、user_id（订阅者的 Telegram ID）、快照条件 （asset、amount、amount_minor、period_days）、status、auto_renew、period_no （已付期数）、current_period_start / current_period_end、created_at、cancelled_at、 cancelled_by（user 或 merchant）、expired_at。

cancelSubscription

POST /pay/api/cancelSubscription——权限范围 subscriptions。一个参数：subscription_id。 它停掉续费（cancelled_by: "merchant"）；已付的那一期到 current_period_end 之前照常能用， 状态立即变为 cancelled，订阅者会收到通知。被取消的订阅者之后可以通过同一条套餐链接重新 授权。返回的是更新后的订阅对象。

错误：404 sub_not_found、409 sub_not_active（已经取消或已经到期）。