> ## 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/cancel-subscription.md)endpoint 发送 `PATCH` 请求。

### 关键请求参数

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

| 参数 | 描述 | 必需的 |
| - | - | - |
| `status` | 必须设置为 `CANCEL` 才能发起取消 | ✅ |

### 示例请求

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

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request PATCH \
     --url https://api.stage.localpayment.com/api/payin/subscriptions/{externalId}/status \
 		 --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     --data-raw '{
    "status": "CANCEL"
}'

```

> [!WARNING]
>
> **重要的**
>
> 订阅一旦取消，便无法重新激活。如果客户希望恢复服务，您需要创建新的订阅。

***

## 步骤 2：处理响应

### 成功响应

成功取消订阅后，系统会返回订阅取消确认信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "a2966037-52a1-4a73-9173-b682969b34ff",
    "internalId": "1ef01791-0e51-4b66-9d45-229895cd49d0",
    "status": {
        "code": "903",
        "description": "CANCELLED",
        "detail": "The subscription was canceled - merchant request"
    }
}
```

### 关键响应字段

| 参数 | 描述 | 用例 |
| - | - | - |
| `internalId` | Localpayment的唯一交易标识符。 | 交易跟踪和支持。 |
| `externalId` | 您的订阅专属参考编号。 | 内部核对。 |
| `status.code` | 取消状态代码（`903` 表示取消成功）。 | 状态监控。 |
| `status.description` | 人类可读的状态描述。 | 用户界面显示。 |
| `status.detail` | 详细的取消信息。 | 审计跟踪。 |

### 错误响应

订阅取消失败时，您将收到错误信息::

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "status": {
        "code": "400",
        "description": "ERROR",
        "detail": "Invalid externalID 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)
>
> 用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。

### 常用状态码

| 代码 | 状态 | 描述 |
| :- | :- | :- |
| `400` | `ERROR` | 取消请求失败。 |
| `903` | `CANCELLED` | 订阅已成功取消。 |

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

***

## 测试您的集成

### 测试场景

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

1. **成功取消**：使用有效凭证取消有效订阅。
2. **已取消的订阅**：尝试取消已取消的订阅。
3. **取消不存在的订阅**：取消一个不存在的订阅。
4. **身份验证错误**：如果身份验证无效或缺失，则取消。
5. **Webhook 通知**：确认取消 Webhook 已触发

***

## 后续步骤

取消订阅后，您可能需要执行其他操作：

> [card] [创建新订阅](https://docs.localpayment.com/zh/docs/create-a-subscription.md)
>
> 如果客户希望使用不同的方案或付款方式恢复服务，
> 请创建新订阅。

> [card] [设置 Webhook](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 配置 Webhook 以接收订阅事件的实时通知。


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