# PayerMax管理订阅计划

## 1. 交互流程

```mermaid
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant User as 用户
    participant MServer as 商户服务端
    participant PM as PayerMax

    %% 首次支付逻辑框
    rect rgb(235, 245, 255)
        Note over User, PM: 首次支付
        User->>MServer: 1. 用户确认订阅计划
同时发起支付请求
        MServer->>PM: 2. 商户向PayerMax
发起创建订阅计划
        PM-->>MServer: 返回订阅ID
        MServer->>PM: 激活订阅
        PM-->>MServer: 3. PayerMax完成支付或绑定，
回传支付及绑定成功信息
        MServer->>User: 4. 通知用户支付或绑定成功
订阅激活成功
    end

    %% 二次支付逻辑框
    rect rgb(235, 245, 255)
        Note over User, PM: 二次支付
        PM->>MServer: 1. PayerMax按照订阅计划
定期扣款并回传支付成功信息
        MServer->>User: 2. 通知用户支付成功
    end
```

## 2. 订阅计划规则说明

::: tip  
PayerMax 订阅计划服务为商户提供灵活的周期性扣款解决方案,支持多种订阅模式,满足不同业务场景的需求。
:::

### 2.1 支持的订阅类型

- **标准订阅**: 按固定周期进行自动扣款的订阅服务

- **试用期订阅**: 提供免费或低价试用期后转为付费订阅的服务

- **优惠期订阅**: 前若干期享受优惠价格的订阅服务

### 2.2 服务限制说明

::: danger 特别提醒：
PayerMax 管理的单个订阅计划总时长不得超过`3年`。
::: 

订阅计划需在规定时间内完成激活,具体要求如下:

1. 订阅计划必须在创建订阅计划`24小时`内完成激活；

2. 超过时效未激活的订阅计划将被系统标记为`过期未激活`状态，PayerMax将向商户发送过期通知。

### 2.3 扣款与通知规则

#### 2.3.1 扣款结果通知规则

| 扣款结果 | 通知时机 | 说明 |
|---------|---------|------|
| 扣款成功 | 立即通知 | 扣款成功后,系统立即向商户发送通知 |
| 扣款失败 | 延迟通知 | 仅在该期最后一次扣款失败后向商户发送通知 |

#### 2.3.2 扣款失败重试机制

当扣款失败时,PayerMax 将自动执行重试机制:

- 系统在重试期间不会向商户发送失败通知,避免频繁通知影响商户系统；

- 重试策略根据商户配置的扣款策略(默认策略/宽限扣款策略)自动执行；

- 仅在所有重试均失败后,系统才会发送最终失败通知。

### 2.4 扣款失败处理策略

#### 2.4.1 默认处理策略

**策略说明**：

订阅激活后，后续扣款由PayerMax系统自动发起。当扣款失败时，PayerMax将会进行重试。若重试后仍然扣款失败，则订阅计划将终止。

#### 2.4.2 扣款失败不终止订阅策略

**策略说明**：

当某期最后一次重试扣款失败后,订阅计划不会终止,订阅状态保持激活。该期无法继续扣款,但下一期开始后,系统将正常发起扣款。

**配置方式**：

此策略需联系PayerMax技术支持团队进行配置。配置以商户号维度生效,配置完成后对该商户号下所有订阅计划立即生效。

### 2.5 扣款时机策略

::: danger 特别提醒：
若商户未联系PayerMax技术支持配置宽限扣款策略，PayerMax将执行默认扣款策略。
::: 

#### 2.5.1 默认扣款策略

**执行流程**：

1. 系统提`前1天`生成下一期扣款账单；

2. 账单生成后立即发起扣款；

3. 扣款失败后，PayerMax将会进行重试；

4. 若重试均失败，则将按照扣款失败处理策略进行处理（终止订阅或不终止订阅）。

#### 2.5.2 宽限扣款策略

**策略说明**：

宽限扣款策略是指在正常扣款失败后,系统在宽限期内继续尝试扣款,为用户提供额外的付款时间窗口,避免因短期资金问题导致订阅立即终止。

**配置方式**：

联系 PayerMax 技术支持团队进行配置。

- 配置维度: 以商户号维度进行配置；

- 生效时机: 配置完成后,在生成下一期扣款账单时生效。

**执行流程**：

1. 系统提`前1天`生成扣款账单并发起扣款；

2. 扣款失败后，PayerMax将会进行重试；

3. 若重试均失败，订阅进入宽限期；

4. 若直到宽限期最后一天仍扣款失败，则将按照扣款失败处理策略进行处理（终止订阅或不终止订阅）。

**宽限期天数扣款规则**：

| 订阅周期类型     | 周期数量范围              | 宽限期可执行扣款的日期   |
| ---------------- | ------------------------- | ------------------------ |
|                  | 1 ≤ periodCount < 7   | 第 1 天                  |
| periodUnit=天(D) | 7 ≤ periodCount < 30  | 第 1, 2, 5 天            |
|                  | 30 ≤ periodCount < 90 | 第 1, 2, 5, 7, 10 天     |
|                  | periodCount ≥ 90         | 第 1, 2, 5, 7, 10, 15 天 |
|                  | 1 ≤ periodCount < 4   | 第 1, 2, 5 天            |
| periodUnit=周(W) | 4 ≤ periodCount < 12  | 第 1, 2, 5, 7, 10 天     |
|                  | periodCount ≥ 12         | 第 1, 2, 5, 7, 10, 15 天 |
| periodUnit=月(M) | 1 ≤ periodCount < 3   | 第 1, 2, 5, 7, 10 天     |
|                  | periodCount ≥ 3          | 第 1, 2, 5, 7, 10, 15 天 |
| periodUnit=年(Y) | 1 ≤ periodCount ≤ 3     | 第 1, 2, 5, 7, 10, 15 天 |

::: tip  示例：
- **示例1**: 订阅周期为`每7天`,宽限期`5天`
  - 正常扣款失败后,系统在该期开始后`第1天`、`第2天`、`第5天`各执行`1次`扣款
  - 期间任一次扣款成功,则停止后续扣款
  - 所有宽限期扣款均失败,则执行扣款失败处理策略

- **示例2**: 订阅周期为`每3个月`,宽限期`15天`
  - 正常扣款失败后,系统在该期开始后`第1天`、`第2天`、`第5天`、`第7天`、`第10天`、`第15天`各执行`1次`扣款
  - 期间任一次扣款成功,则停止后续扣款
  - 所有宽限期扣款均失败,则执行扣款失败处理策略
:::

### 2.6 策略配置说明

#### 2.6.1 配置维度

所有扣款策略配置均以商户号维度进行,配置完成后对该商户号下的订阅计划生效。

#### 2.6.2 配置生效时机

| 策略类型 | 生效时机 |
|---------|---------|
| 扣款失败处理策略 | 配置完成后对所有订阅计划立即生效 |
| 宽限扣款策略 | 配置完成后,在生成下一期扣款账单时生效 |

## 3. 订阅计划状态说明

| 状态值        | 状态说明   | 备注                                 |
| ------------- | ---------- | ------------------------------------ |
| INACTIVE      | 未激活     | 创建订阅计划后，状态为未激活         |
| ACTIVE_FAILED | 激活失败   | 激活失败后的状态                     |
| ACTIVE        | 生效中     | 激活成功后的状态                     |
| TERMINATE     | 订阅终止   | 某期扣款失败后，订阅计划会终止       |
| CANCEL        | 订阅取消   | 主动取消订阅计划                     |
| FINISH        | 订阅完成   | 订阅计划所有期数都完成扣款           |
| EXPIRED       | 过期未激活 | 首期扣款时间开始后，还未激活订阅计划 |

## 4. 订阅扣款状态说明

| 状态值  | 状态说明 |
| ------- | -------- |
| PENDING | 扣款中   |
| SUCCESS | 扣款成功 |
| FAILED  | 扣款失败 |