> ## 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/docs/get-subscription-plan.md)endpoint 发送 `GET` 请求。

### 关键请求参数

该请求需要几个关键参数：

| 参数 | 说明 | 必需 |
| - | - | - |
| `internalId` | 从 URL 路径获取 Localpayment 的唯一计划标识符 | ✅ |

### 示例请求

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

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request GET \
  --url 'https://api.stage.localpayment.com/api/subscriptions/plan/{internalId}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json'
```

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

***

## 步骤 2：处理响应

### 成功响应

请求成功后，将返回完整的订阅计划详情：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "internalId": "b8546575-5d4f-4a56-9e21-522d01cf5992",
    "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",
        "frequency": 1
    },
    "status": {
        "code": "100",
        "description": "ACTIVE",
        "detail": "Subscription plan is active"
    }
}
```

### 关键响应字段

| 参数 | 说明 | 用例 |
| - | - | - |
| `internalId` | Localpayment 的唯一计划标识符。 | API操作参考。 |
| `name` | 订阅计划的描述性名称。 | 向顾客展示。 |
| `description` | 方案特点详解。 | 客户沟通。 |
| `amount` | 账单金额。 | 支付处理。 |
| `country` | 该计划适用的国家/地区。 | 地理限制。 |
| `currency` | 结算货币。 | 财务计算。 |
| `accountNumber` | 关联的商户账号。 | 对账。 |
| `autoRecurring.type` | 计费频率类型。 | 账单周期管理。 |
| `autoRecurring.repetitions` | 账单周期数。 | 计划持续时间跟踪。 |
| `autoRecurring.frequency` | 计费频率值。 | 设置定期计费。 |
| `status.code` | 当前计划状态代码。 | 检查可用性。 |

### 错误响应

如果找不到或无法访问订阅计划，您将收到错误信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "status": {
    "code": "400",
    "description": "ERROR",
    "detail": "Plan subscription not found"
  }
}
```

***

## 步骤 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. **无效的计划 ID**：请使用格式错误或不正确的 internalId 格式进行测试。
4. **身份验证失败**：检索具有无效或过期访问令牌的计划。

***

## 后续步骤

> [card] [创建订阅计划](https://docs.localpayment.com/zh/docs/create-a-subscription-plan.md)
>
> 针对不同的服务级别或定价模式，制定新的订阅计划。

> [card] [更新订阅计划](https://docs.localpayment.com/zh/docs/update-a-subscription-plan.md)
>
> 根据获取的信息修改现有计划细节。

> [card] [使用计划创建订阅](https://docs.localpayment.com/zh/docs/create-a-subscription.md)
>
> 使用计划 ID 创建新的客户订阅。


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