> ## 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 以接收付款通知。

***

## 步骤 1：创建订阅

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

### 关键请求参数

该请求需要若干关键参数，具体取决于您创建的是固定计划订阅还是自定义订阅：

| 参数 | 说明 | 必需的 |
| - | - | - |
| `externalId` | 您的订阅专属参考编号 | ✅ |
| `merchant` | 商家/企业详情 | ✅ |
| `country` | 订阅的处理所在国家/地区代码 | ✅ |
| `currency` | 订阅的货币代码 | ✅ |
| `paymentMethod` | 支付方式配置 | ✅ |
| `planId` | 预定义订阅计划的 ID（适用于固定计划） | ❌ |
| `autoRecurring` | 计费频率 | 视情况而定 |
| `amount` | 订阅金额（未提供 planId 时必填） | 视情况而定 |

### 订阅类型

* **固定计划订阅**：适用于已通过[创建订阅计划](https://docs.localpayment.com/zh/docs/create-a-subscription-plan.md)endpoint 创建了预定义订阅计划的情况。
* **自定义订阅**：适用于每次付款金额或时间可能不同的浮动计费场景。

### 支付方式代码

在每个国家/地区，`paymentMethod.code` 都用于标识国家/地区、卡品牌和产品（信用卡或借记卡），因此请发送与卡片及订阅的 `country` 相匹配的代码。在秘鲁，卡片支持两种货币，代码还必须与 `currency` 相匹配：例如，Visa 信用卡在使用 PEN 时为 `6000`，使用 USD 时为 `6004`。所有国家/地区的代码请参阅[银行卡支付方式代码](https://docs.localpayment.com/zh/docs/card-payment-methods.md)。

### 示例请求

以下是使用 `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/payin/subscriptions \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1900",
        "flow": "DIRECT"
    },
    "externalId": "1fe38b94-7e11-44c1-9a88-b4aa9fbe5b4a",
    "country": "COL",
    "amount": 10000.00,
    "currency": "COP",
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "comment": "Test subscription",
    "merchant": {
        "type": "COMPANY",
        "name": "My Company SA DE CV",
        "document": {
            "type": "CC",
            "id": "717321230"
        }
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "id": "1073695321",
            "type": "CC"
        },
        "email": "john.doe@example.com"
    },
    "card": {
        "name": "John Doe",
        "number": "4242424242424242",
        "cvv": "123",
        "expirationMonth": "11",
        "expirationYear": "2029",
        "installments": 1
    },
    "type": "SOFTWARE",
    "autoRecurring": {
        "type": "day"
    }
}'
'

```

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

***

## 步骤 2：处理响应

### 成功响应

成功的响应包含详细的订阅信息和标识符：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "type": "SOFTWARE",
    "externalId": "1fe38b94-7e11-44c1-9a88-b4aa9fbe5b4a",
    "internalId": "990017f0-7928-4c20-a149-0c1673035f2c",
    "country": "COL",
    "currency": "COP",
    "accountNumber": "{{accountNumber}}",
    "status": {
        "code": "105",
        "description": "WAITINGAUTH",
        "detail": "The subscription is active"
    },
    "date": {
        "creationDate": "2025-11-13T05:05:58.8502173",
        "nextPaymentDate": "2025-11-14T05:05:58.8502036"
    },
    "payments": [
        {
            "externalId": "36e1ce13-8a20-4565-b5f5-e275e1df0010",
            "internalId": "adccc452-4a8c-414c-b777-152f4b0ed2da",
            "status": {
                "code": "100",
                "description": "INPROGRESS",
                "detail": "The payin is pending the confirmation"
            },
            "redirectUrl": "https://web-checkout.stage.localpayment.com/redirect/aHR0cHM6Ly93ZWItY2hlY2tvdXQuc3RhZ2UubG9jYWxwYXltZW50LmNvbS92ZXJpZmljYXRpb24vMDA5Nz9pbnRlcm5hbElkPTQzYzVjZDE1LTg0N2UtNDRhNC05MTU1LTcyYmVmNjZiZDAzMw"
        }
    ],
    "errors": []
}
```

### 关键响应字段

| 参数 | 说明 | 用例 |
| - | - | - |
| `internalId` | Localpayment 唯一的订阅标识符。 | 订阅跟踪与管理。 |
| `status.code` | 当前订阅状态代码。 | 状态监控与自动化。 |
| `date.creationDate` | 订阅的创建时间 | 审计追踪和报告。 |
| `date.nextPaymentDate` | 下一次付款的处理时间。 | 账单周期管理。 |
| `payments` | 该订阅的付款对象数组。 | 付款历史与跟踪。 |

### 错误响应

请求失败时，您将收到详细的错误信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "b27ebf99-e92d-4aca-ba16-f9f8412372cd",
    "internalId": "f95883ce-f08a-485f-9734-0182ec3af70d",
    "country": "COL",
    "currency": "COP",
    "accountNumber": "{{accountNumber}}",
    "type": "SOFTWARE",
    "autoRecurring": {
        "type": "day"
    },
    "status": {
        "code": "300",
        "description": "REJECTED"
    },
    "date": {
        "creationDate": "2025-11-13T05:07:42.7612531"
    },
    "payments": [
        {
            "externalId": "672022a9-b595-4d78-88d0-6ac8d6738082",
            "internalId": "8279db2d-2502-4c1f-8d3b-b668c8b5ff53",
            "status": {
                "code": "300",
                "description": "REJECTED"
            }
        }
    ],
    "errors": [
        {
            "code": "300",
            "detail": "Invalid param + [payer.email] + must not be null"
        }
    ]
}
```

***

## 步骤 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)
>
> 用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。

### 常用状态码

Localpayment API 提供多种状态码，用于指示订阅的状态。

| 代码 | 状态 | 说明 |
| :- | :- | :- |
| `105` | `ACTIVE` | 订阅已生效并正在进行中。 |
| `300` | `REJECTED` | 订阅创建或付款被拒绝。 |

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

***

## 测试您的集成

### 测试场景

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

1. **订阅创建成功**：使用有效银行卡的标准订阅流程。
2. **固定计划订阅**：使用预定义计划的订阅。
3. **自定义订阅**：使用自定义计费参数的订阅。
4. **验证错误**：无效的银行卡、缺少必填字段
5. **状态更新**：Webhook 处理和状态轮询

***

## 后续步骤

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

> [card] [更新订阅](https://docs.localpayment.com/zh/docs/update-a-subscription.md)
>
> 修改现有订阅详情，包括计费金额、频率或
> 客户信息。

> [card] [取消订阅](https://docs.localpayment.com/zh/docs/cancel-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.