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

# 创建订阅计划

Localpayment 使您能够创建固定订阅计划，以实现标准化的周期性计费。本指南详细介绍了如何通过 Localpayment 的 API 设置订阅计划，然后将这些计划与客户订阅关联起来，从而实现一致的自动化计费。

## 开始之前

请确保您已备好：

> [card] [API凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)
>
> 用于身份验证的有效 API 凭据和访问令牌。

> [card] [账户设置](https://docs.localpayment.com/zh/docs/make-your-first-test-payment.md)
>
> 为您的目标国家/地区正确设置账户并进行业务验证。

> [card] [IP白名单](https://docs.localpayment.com/zh/docs/dashboard-whitelist-your-ips.md)
>
> 将服务器 IP 地址加入 API 访问白名单。

> [card] [Webhook endpoint](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 设置 webhook URL 以接收付款通知。

***

## 第一步：创建订阅计划

要创建新的订阅计划，请向[创建订阅计划](https://docs.localpayment.com/zh/reference/create-subscription-plan)endpoint 发送 `POST` 请求。

### 关键请求参数

该请求需要几个关键对象：

| 参数 | 说明 | 必需的 |
| - | - | - |
| `name` | 订阅计划的描述性名称 | ✅ |
| `description` | 详细解释计划特点和优势 | ❌ |
| `country` | 该计划适用的国家/地区代码 | ✅ |
| `amount` | 固定账单金额 | ✅ |
| `currency` | 计费货币代码 | ✅ |
| `accountNumber` | 您的商户账号 | ✅ |
| `autoRecurring.repetitions` | 计费周期数（按需周期请使用 `0`） | ✅ |
| `autoRecurring.type` | 计费频率单位（按需周期请使用 `custom`） | |

### 支持的计费频率

> [card] 每日
>
> 每日向客户收费。非常适合每日使用量大或
> 短期使用的服务。
>
> 发送 `autoRecurring.type` 属性，值为：`day`

> [card] 月度
>
> 适用于大多数 SaaS 产品、会员服务和
> 订阅盒的按月定期计费。
>
> 发送 `autoRecurring.type` 属性，值为：`month`

> [card] 定制（按需）
>
> 适用于使用量不固定场景的按需计费。非常适合
> 按量付费或基于使用量的服务。
>
> 发送 `autoRecurring.type` 属性，值为：`custom`

### 示例请求

以下是使用 `curl` 的示例：

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
  --url https://api.stage.localpayment.com/api/subscriptions/plan \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Plan Básico Mensual",
    "description": "Acceso básico a contenido exclusivo",
    "country": "MEX",
    "amount": 50,
    "currency": "MXN",
    "accountNumber": "{{accountNumber}}",
    "autoRecurring": {
      "repetitions": 1,
      "type": "hour"
    }
  }'
```

查看请求中所有[可用的参数](https://docs.localpayment.com/zh/reference/create-subscription-plan)。

***

## 步骤 2：处理响应

### 成功响应

成功创建的订阅计划将显示完整的计划详情：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "internalId": "70af52e2-ea99-46a8-a931-65f15f6a3c20",
    "name": "Plan Básico Mensual",
    "description": "Acceso básico a contenido exclusivo",
    "amount": 50,
    "country": "MEX",
    "currency": "MXN",
    "accountNumber": "{{accountNumber}}",
    "autoRecurring": {
        "repetitions": 1,
        "type": "hour"
    },
    "status": {
        "code": "100",
        "description": "ACTIVE",
        "detail": "Subscription plan is active"
    }
}
```

### 关键响应字段

| 参数 | 说明 | 用例 |
| - | - | - |
| `internalId` | Localpayment 唯一的计划标识符。 | 创建订阅时用作 `planId` |
| `status.code` | 当前计划状态代码。 | 状态监控。 |
| `autoRecurring.type` | 已确认的计费频率。 | 账单周期核实。 |
| `autoRecurring.repetitions` | 已确认的计费周期数。 | 计划持续时间跟踪。 |

### 错误响应

订阅计划创建失败时，您将收到详细的错误信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "status": {
        "code": "400",
        "description": "REJECTED",
        "detail": "autoRecurring.type is required"
    }
}
```

***

## 步骤 3：跟踪交易状态

创建订阅计划后，可通过以下方法监控其状态：

> [card] [Webhooks（推荐）](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 交易状态变更时接收实时通知。最适用于生产环境。

> [card] [状态 API endpoint](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 以编程方式查询事务状态。可用于轮询或恢复丢失的 webhook 通知。

> [card] [Business Portal 视图](https://docs.localpayment.com/zh/docs/dashboard-overview.md)
>
> 用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。

### 常用状态码

| 代码 | 状态 | 说明 |
| :- | :- | :- |
| `100` | `ACTIVE` | 该计划已生效，可用于订阅关联。 |
| `400` | `REJECTED` | 由于验证错误或参数无效，计划创建失败。 |

> [!NOTE]
>
> **完整参考**
>
> 请查看我们的[交易状态文档](https://docs.localpayment.com/zh/reference/transaction-status-error-codes)，了解所有状态代码。

***

## 测试您的集成

### 测试场景

请确认您的集成方案能够处理以下场景：

1. **计划创建成功**：使用有效参数创建标准计划。
2. **分级定价结构**：创建多个不同价位的套餐。
3. **多种计费频率**：测试每日、每月和自定义按需计划。
4. **验证错误**：缺少必填字段、金额无效、国家/地区不受支持。
5. **订阅关联**：测试计划能否成功与订阅关联

***

## 后续步骤

创建订阅计划后，您可能需要执行其他操作：

> [card] [使用计划创建订阅](https://docs.localpayment.com/zh/docs/create-a-subscription.md)
>
> 将计划的 internalId 用作 planId 参数，
> 使用您的新计划创建客户订阅。

> [card] [更新订阅计划](https://docs.localpayment.com/zh/docs/update-a-subscription-plan.md)
>
> 修改现有计划详情，同时保持与
> 有效订阅的关联。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.