> ## Documentation Index
> Fetch the complete documentation index at: https://doc.haipay.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 订阅支付流程图

> 用更清晰的阶段拆解 HaiPay 订阅支付全流程，包括创建订阅、周期扣款、取消订阅和异常重试逻辑。

本文梳理 HaiPay 订阅业务从创建到终止的完整流程。建议先看下方流程摘要，再查看各阶段图示，具体接入请参考 [订阅支付接口](/docs/zh/V20260628/api/version2/Subscription) 和 [API Reference](/docs/zh/api-reference/subscription/api/subscriptionApply)。

<Columns cols={3}>
  <Card title="创建订阅" icon="circle-plus" href="#create-subscription">
    用户授权订阅，完成首笔支付，并生成平台订阅号。
  </Card>

  <Card title="周期扣款" icon="arrows-rotate" href="#recurring-charge">
    HaiPay 按周期自动扣款，并把结果异步通知给商户。
  </Card>

  <Card title="取消与结束" icon="ban" href="#cancel-subscription">
    用户取消、超过最大周期或重试失败时，订阅结束。
  </Card>
</Columns>

## 流程摘要

<Steps>
  <Step title="用户发起订阅">
    商户调用订阅申请接口，HaiPay 返回授权地址或前端组件所需的支付令牌，用户完成授权与首笔支付。
  </Step>

  <Step title="订阅进入有效状态">
    首次支付成功后，平台生成 `subscriptionNo`，后续自动扣款都围绕这个订阅号进行。
  </Step>

  <Step title="平台按周期自动扣款">
    到达扣款周期后，HaiPay 自动发起扣款，并通过异步通知将结果同步给商户。
  </Step>

  <Step title="达到结束条件后终止">
    当用户主动取消、达到最大循环次数，或连续失败达到终止条件时，订阅结束。
  </Step>
</Steps>

## 关键状态理解

| 阶段   | 你需要关注什么                       |
| :--- | :---------------------------- |
| 创建订阅 | 是否成功返回授权入口、用户是否完成首次授权与首笔支付    |
| 订阅成功 | 是否拿到 `subscriptionNo` 并完成本地落库 |
| 周期扣款 | 是否正确接收并处理每次异步扣款通知             |
| 取消订阅 | 是否为用户提供清晰的退订入口，并同步取消结果        |
| 异常重试 | 是否对失败扣款做好风控、通知和业务补偿策略         |

<Tip title="实施建议">
  * 首次支付成功后，立即保存 `subscriptionNo`、商户订阅号和用户标识之间的关系。
  * 不要只依赖前端结果页，订阅状态与扣款结果都应以服务端通知和查询接口为准。
  * 订阅业务务必向用户展示周期、金额、取消方式和服务协议。
</Tip>

<a id="create-subscription" />

## 创建订阅

**目标**：完成用户授权与首笔订阅支付，并建立订阅关系。

```mermaid theme={null}
sequenceDiagram
    participant 用户
    participant 商户
    participant HaiPay

    用户->>商户: 1. 选择订阅服务
    商户->>HaiPay: 2. 调用 apply API 创建订阅
    HaiPay-->>商户: 3. 返回授权 URL / 前端支付能力
    商户-->>用户: 4. 引导用户进入授权页面
    用户->>HaiPay: 5. 完成支付认证与授权
    HaiPay->>HaiPay: 6. 校验授权状态
    HaiPay->>HaiPay: 7. 发起首笔订阅扣款
    HaiPay-->>商户: 8. 通知订阅结果
    商户-->>用户: 9. 展示订阅开通结果
```

**这一阶段的落地重点**

* 商户侧要保存商户订阅号与平台订阅号映射
* 首笔支付结果不要只看前端页面，要结合通知或查询接口确认
* 用户侧要清楚知道订阅金额、周期和取消方式

<a id="recurring-charge" />

## 周期扣款

**目标**：在订阅有效期间，按约定周期自动续费。

```mermaid theme={null}
sequenceDiagram
    participant 用户
    participant 商户
    participant HaiPay

    HaiPay->>HaiPay: 1. 到期后自动发起周期扣款
    HaiPay-->>商户: 2. 异步发送扣款结果
    商户-->>用户: 3. 更新订阅权益或发送续费通知
```

**这一阶段的落地重点**

* 服务端必须处理异步通知，并返回大写 `SUCCESS`
* 建议在每次扣款前后都向用户发送站外提醒
* 如果扣款失败，商户侧要定义好重试、降级或暂停服务策略

<Warning title="不要忽略回调处理">
  如果只依赖用户是否打开结果页，你会漏掉真实的周期扣款状态。订阅续费场景必须以服务端通知和查询接口做最终确认。
</Warning>

<a id="cancel-subscription" />

## 取消订阅

**目标**：在用户申请退订或业务终止时，及时停止后续扣款。

```mermaid theme={null}
sequenceDiagram
    participant 用户
    participant 商户
    participant HaiPay

    用户->>商户: 1. 发起取消订阅
    商户->>HaiPay: 2. 调用 cancel API
    HaiPay-->>商户: 3. 返回取消结果
    商户-->>用户: 4. 展示取消状态
```

**这一阶段的落地重点**

* 用户侧必须有清晰、可访问的取消入口
* 取消成功后，要同步更新本地订阅状态
* 如果取消前存在待处理扣款，需要在业务上明确最终权益边界

## 完整生命周期图

```mermaid theme={null}
graph TD
  A[创建订阅] --> B[首次支付]
  B --> C[支付成功]
  B --> D[支付失败]
  D --> E[订阅失败]
  E --> A
  C --> F[订阅成功]
  F --> G[到达扣款周期，检查最大循环次数]
  G --> N[超过最大次数]
  N --> M[取消订阅]
  G --> L[未超过最大次数]
  L --> O[发起自动扣款]
  O --> H[扣款成功]
  H --> G
  O --> I[扣款失败]
  I --> G
  I --> K[失败后进入重试/终止判断]
  K --> M[取消订阅]
```

## 相关主题

* [订阅支付接口](/docs/zh/V20260628/api/version2/Subscription)
* [订阅申请](/docs/zh/api-reference/subscription/api/subscriptionApply)
* [查询订阅](/docs/zh/api-reference/subscription/api/subscriptionQuery)
* [取消订阅](/docs/zh/api-reference/subscription/api/subscriptionCancel)