稳定币订阅支付

基于首次钱包授权和后续自动续费的稳定币订阅支付。

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 店铺，从付款人视角体验首次订阅授权。

如果你需要一张不属于周期计划的单次客户账单，请使用 Invoicing。如果你只需要一次性付款，请使用 Stablecoin Checkout。

​

产品模型

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，并按重试策略自动恢复。	应用宽限期、功能限制或提醒策略。
取消订阅	支持立即取消或账期结束取消。	同步取消状态，并在正确时间关闭权益。

​

工作流程

1. 商家后端为某个 customer 和 plan 创建 subscription，传入金额、账期、启动方式和回跳信息。
2. StablePay 返回 hosted checkout URL，用于首次授权或首期支付。
3. 客户在 StablePay Hosted Checkout 中选择钱包、确认信息、签名授权，并在需要时支付首期。
4. StablePay 保存可复用的授权 / payment method，用于后续账期扣款。
5. 每个账期到来时，StablePay 创建 invoice，并尝试 off-session 自动扣款。
6. StablePay 通过 Webhook 推送 subscription、invoice 和 payment 结果。
7. 商家系统根据 Webhook 开通、延续、限制或关闭客户权益。

​

订阅启动方式

模式	说明	适合场景
立即开始并立即扣首期	首张 invoice 在 checkout 中支付，支付成功后订阅生效。	标准付费订阅，用户今天开始使用。
立即开始但延后首扣	客户在 checkout 中只完成授权，首张 invoice 在未来扣款日自动扣款。	需要先开通服务，稍后首次计费。
Trial 试用	客户在 checkout 中只完成授权，试用结束时生成首张 invoice 并自动扣款。	免费试用、延迟转化或先体验后付费。

​

Retry 与 Dunning

续费失败后的自动恢复称为 Dunning。续费付款可能因为钱包余额、授权、网络或合规条件而失败。当最近一期应收款扣款失败时，StablePay 会让订阅进入 past_due，发送 Webhook，并执行默认重试策略。

默认重试节奏：

重试	时间
1	失败后 5 分钟
2	失败后 30 分钟
3	失败后 2 小时
4	失败后 20 小时

如果任意一次重试成功，invoice 会变为 paid，subscription 可恢复为 active，并继续进入下一账期。如果重试全部失败，subscription 会自动变为 canceled，不再继续生成新账期。

商家应避免每次重试失败都打扰用户。更好的做法是：在首次失败时发送一次余额或钱包提醒，并根据业务策略决定是否提供宽限期、限制功能或暂时保持服务可用。

​

取消订阅

StablePay 支持两类取消方式：

取消方式	行为	商家应该如何处理
到期取消	当前账期继续有效，到期后 subscription 变为 canceled。	展示“将在本期结束时取消”，并在 current_period_end 后关闭权益。
立即取消	subscription 立即终止。	立即关闭权益或进入你的退款 / 客服流程。

到期取消通常会先更新 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 驱动。

​

上线建议

​

新商户第一次上线订阅

建议先上线“立即开始并立即扣首期”，验证转化率、客服压力、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 应作为权益、服务访问和内部账单状态的主要状态来源。

​

相关页面

• Stablecoin Checkout
• Invoicing
• Refunds
• Supported Wallets
• Supported Networks
• Currencies & Auto Currency Conversion