> ## 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](/zh/product/Stablecoin-Checkout) 的定位不同。Checkout 用于一次性付款；Subscriptions 用于重复收费。客户先在 StablePay Hosted Checkout 中完成 on-session 钱包授权，之后每个账期由 StablePay 创建 invoice，并基于已保存的授权执行 off-session 自动续费扣款。

## 适用场景

当你与客户之间存在持续的周期性商业关系时，适合使用 Stablecoin Subscriptions。

常见场景包括：

* 月付或年付 SaaS 套餐。
* 会员、订阅和付费社区。
* 软件、内容、游戏或服务的高级访问权限。
* Retainer、周期支持服务或客户经理维护的服务包。
* 只有在计费保持有效时才应持续提供访问权限的业务。

## 体验 demo

你可以访问下面的订阅演示店铺，体验 StablePay Subscriptions Checkout 的首次授权流程：

<Card title="Subscription demo storefront" icon="repeat" href="https://mall.wenfu.shop/subscription">
  打开订阅 demo 店铺，从付款人视角体验首次订阅授权。
</Card>

如果你需要一张不属于周期计划的单次客户账单，请使用 [Invoicing](/zh/product/Invoicing)。如果你只需要一次性付款，请使用 [Stablecoin Checkout](/zh/product/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](/zh/product/Supported-Wallets)、[Supported Networks](/zh/product/Supported-Networks) 和 [Currencies & Auto Currency Conversion](/zh/product/Auto-Currency-Conversion)。

## 重要说明

* 自动续费扣款前，需要客户完成首次钱包授权。
* Subscriptions Checkout 仅支持连接钱包授权，不支持 QR Code / 地址转账付款。
* `subscription.created` 不代表客户已授权或已支付，正式权益应以 Webhook 事件为准。
* `subscription.active` 表示订阅处于正常状态，但“钱确实到账”的更直接信号是 `invoice.paid`。
* Refund 针对 payment 发起，不直接针对 subscription object。
* Webhook 应作为权益、服务访问和内部账单状态的主要状态来源。

## 相关页面

* [Stablecoin Checkout](/zh/product/Stablecoin-Checkout)
* [Invoicing](/zh/product/Invoicing)
* [Refunds](/zh/product/Refunds)
* [Supported Wallets](/zh/product/Supported-Wallets)
* [Supported Networks](/zh/product/Supported-Networks)
* [Currencies & Auto Currency Conversion](/zh/product/Auto-Currency-Conversion)