Documentation Index
Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt
Use this file to discover all available pages before exploring further.
Stablecoin Subscriptions 是 StablePay 面向周期性稳定币计费的产品。它帮助商家管理客户订阅的完整生命周期：创建订阅、完成首次钱包授权、按账期自动扣款、处理续费失败与重试、取消订阅，以及通过 Webhook 同步业务状态。
它与 Stablecoin Checkout 的定位不同。Checkout 用于一次性付款；Subscriptions 用于重复收费。客户先在 StablePay Hosted Checkout 中完成 on-session 钱包授权，之后每个账期由 StablePay 创建 invoice，并基于已保存的授权执行 off-session 自动续费扣款。
适用场景
当你与客户之间存在持续的周期性商业关系时，适合使用 Stablecoin Subscriptions。
常见场景包括：
- 月付或年付 SaaS 套餐。
- 会员、订阅和付费社区。
- 软件、内容、游戏或服务的高级访问权限。
- Retainer、周期支持服务或客户经理维护的服务包。
- 只有在计费保持有效时才应持续提供访问权限的业务。
体验 demo
你可以访问下面的订阅演示店铺，体验 StablePay Subscriptions Checkout 的首次授权流程：
Subscription demo storefront
打开订阅 demo 店铺，从付款人视角体验首次订阅授权。
产品模型
Stablecoin Subscriptions 的核心模型是“首次授权 + 账期 invoice + 自动续费 + Webhook 驱动权益”。
| 阶段 | StablePay 处理 | 商家系统应该做什么 |
|---|
| 创建订阅 | 创建 subscription，并返回首次授权用的 hosted checkout URL。 | 保存 subscription_id，将客户跳转到 checkout。 |
| 首次授权 | 客户在 checkout 中选择钱包、完成链上授权，并可同时支付首期。 | 等待 Webhook，不要仅凭创建成功就开通正式权益。 |
| 账期运行 | 每个账期生成 invoice，并在到期时自动尝试扣款。 | 根据 invoice 和 subscription Webhook 更新本地状态。 |
| 续费成功 | 续费 payment 成功，invoice 变为 paid，subscription 保持 active。 | 延长或确认客户权益，并可发送续费成功通知。 |
| 续费失败 | 订阅进入 past_due，并按重试策略自动恢复。 | 应用宽限期、功能限制或提醒策略。 |
| 取消订阅 | 支持立即取消或账期结束取消。 | 同步取消状态，并在正确时间关闭权益。 |
工作流程
- 商家后端为某个 customer 和 plan 创建 subscription，传入金额、账期、启动方式和回跳信息。
- StablePay 返回 hosted checkout URL，用于首次授权或首期支付。
- 客户在 StablePay Hosted Checkout 中选择钱包、确认信息、签名授权，并在需要时支付首期。
- StablePay 保存可复用的授权 / payment method，用于后续账期扣款。
- 每个账期到来时，StablePay 创建 invoice，并尝试 off-session 自动扣款。
- StablePay 通过 Webhook 推送 subscription、invoice 和 payment 结果。
- 商家系统根据 Webhook 开通、延续、限制或关闭客户权益。
订阅启动方式
| 模式 | 说明 | 适合场景 |
|---|
| 立即开始并立即扣首期 | 首张 invoice 在 checkout 中支付，支付成功后订阅生效。 | 标准付费订阅，用户今天开始使用。 |
| 立即开始但延后首扣 | 客户在 checkout 中只完成授权，首张 invoice 在未来扣款日自动扣款。 | 需要先开通服务，稍后首次计费。 |
| Trial 试用 | 客户在 checkout 中只完成授权，试用结束时生成首张 invoice 并自动扣款。 | 免费试用、延迟转化或先体验后付费。 |
Retry 与 Dunning
续费失败后的自动恢复称为 Dunning。续费付款可能因为钱包余额、授权、网络或合规条件而失败。当最近一期应收款扣款失败时，StablePay 会让订阅进入 past_due，发送 Webhook，并执行默认重试策略。
默认重试节奏：
| 重试 | 时间 |
|---|
| 1 | 失败后 5 分钟 |
| 2 | 失败后 30 分钟 |
| 3 | 失败后 2 小时 |
| 4 | 失败后 20 小时 |
active，并继续进入下一账期。如果重试全部失败，subscription 会自动变为 canceled，不再继续生成新账期。
商家应避免每次重试失败都打扰用户。更好的做法是：在首次失败时发送一次余额或钱包提醒，并根据业务策略决定是否提供宽限期、限制功能或暂时保持服务可用。
取消订阅
StablePay 支持两类取消方式：
| 取消方式 | 行为 | 商家应该如何处理 |
|---|
| 到期取消 | 当前账期继续有效，到期后 subscription 变为 canceled。 | 展示“将在本期结束时取消”，并在 current_period_end 后关闭权益。 |
| 立即取消 | subscription 立即终止。 | 立即关闭权益或进入你的退款 / 客服流程。 |
cancel_at_period_end=true，真正终止时再收到 subscription.canceled。商家不应把 subscription.updated 直接当作订阅已终止。
Webhook 事件
Webhook 是订阅接入的状态来源。商家应使用 subscription.id 与 event_id 做幂等去重，并以 Webhook payload 中的最新对象为准，避免乱序事件造成状态回退。
Subscription events
| 事件 | 触发时机 | 商家应该做什么 |
|---|
subscription.created | 商家成功创建 subscription，订阅对象已生成。 | 创建本地 pending 订阅记录，保存 customer、plan、subscription_id 和 checkout_url。 |
subscription.trialing | 客户完成首次授权，且订阅进入试用期。 | 开通试用权益，展示试用结束时间和后续自动扣款提示。 |
subscription.active | 订阅进入正常可续费状态，或 past_due 重试成功恢复。 | 开通或恢复正式权益。是否已付款应结合 invoice.paid 判断。 |
subscription.past_due | 最近一期扣款失败，订阅进入逾期并正在重试。 | 标记续费失败，应用宽限期或限制策略，并触发一次提醒。 |
subscription.updated | 订阅对象可变字段变化，例如到期取消标记更新。 | 同步取消状态，向用户展示清晰的到期取消信息。 |
subscription.canceled | 订阅终止，不再生成新账期。 | 关闭权益或设置到期失效，停止续费提醒。 |
subscription.incomplete_expired | 创建后用户未在规定时间内完成首次授权，例如 30 分钟内未完成。 | 标记为 onboarding failed / expired，并允许用户重新创建订阅。 |
Invoice and refund events
| 事件 | 触发时机 | 商家应该做什么 |
|---|
invoice.created | 生成首期或续费账单。 | 记录 invoice_id、金额、币种和账期区间。 |
invoice.paid | invoice 支付成功。 | 将 invoice 标记为 paid，并延长或确认客户权益。 |
invoice.payment_failed | 首期或续费扣款失败，或重试失败。 | 记录失败状态，并根据 subscription 状态执行提醒或限制策略。 |
refund.created | 创建退款请求或退款记录。 | 创建本地 refund 记录，并标记退款处理中。 |
refund.succeeded | 退款成功完成。 | 将 refund 标记为 succeeded，并更新订单或账单的退款展示。 |
refund.failed | 退款处理失败。 | 标记失败，并根据失败原因进入客服或重试流程。 |
状态机
订阅状态的关键变化规则：
| 状态变化 | 含义 |
|---|
incomplete → incomplete_expired | 首次授权超过有效时间未完成。 |
active → past_due | 续费扣款失败。 |
past_due → active | 自动重试成功。 |
past_due → canceled | 重试耗尽后系统自动取消。 |
active / trialing / past_due → canceled | 用户或商家取消，立即或到期生效。 |
上线建议
新商户第一次上线订阅
建议先上线“立即开始并立即扣首期”，验证转化率、客服压力、Webhook 状态同步和对账流程。等激活与续费链路稳定后，再增加 Trial。只有在业务确实需要对齐账单日或未来扣款日时，再引入“首期延后扣”。
已有银行卡订阅，新增稳定币订阅
建议将稳定币订阅作为并行支付方式提供，而不是直接替换现有卡订阅。用户主动选择或切换到 StablePay 后，再创建新的 StablePay subscription，并将原卡订阅设置为到期取消，避免同一权益被重复扣款。
支付方式、币种和网络
Stablecoin Subscriptions 当前支持使用 USD 创建订阅，并通过 USDT / USDC 完成稳定币扣款与结算。订阅场景可支持 MetaMask、Binance Wallet、OKX Wallet 和 WalletConnect 等钱包，以及 Ethereum、BNB Smart Chain 和 Solana 等网络。
StablePay Subscriptions Checkout 不支持扫码地址转账或复制地址转账。周期计费需要客户通过支持的连接钱包流程授权未来扣款。
具体可用范围可能因商家配置、环境和合规要求而不同。完整支持范围请参考 Supported Wallets、Supported Networks 和 Currencies & Auto Currency Conversion。
重要说明
- 自动续费扣款前，需要客户完成首次钱包授权。
- Subscriptions Checkout 仅支持连接钱包授权，不支持 QR Code / 地址转账付款。
subscription.created 不代表客户已授权或已支付，正式权益应以 Webhook 事件为准。subscription.active 表示订阅处于正常状态，但“钱确实到账”的更直接信号是 invoice.paid。- Refund 针对 payment 发起，不直接针对 subscription object。
- Webhook 应作为权益、服务访问和内部账单状态的主要状态来源。
相关页面
