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

### 关键请求参数

| 对象 | 描述 | 必需的 |
| - | - | - |
| `paymentMethod.code` | 支付方式代码。仅支持 `CreditCard` 方式。 | ✅ |
| `amount` | 交易总金额 | ✅ |
| `currency` | 交易货币代码 | ✅ |
| `country` | 将处理付款的国家/地区 | ✅ |

> [!NOTE]
>
> 分期付款仅适用于本地货币。在秘鲁，您可以对 PEN 付款提供分期付款，但不能对 USD 付款提供分期付款。

### 示例请求

以下是使用 `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/installments-plans \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "paymentMethod": {
    "code": "1600"
  },
  "country": "MEX",
  "currency": "MXN",
  "amount": 1000,
  "accountNumber": "{{accountNumber}}"
}
'
```

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

***

## 步骤 2：处理报价响应

### 成功响应

成功的分期付款报价包含详细的付款计划信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "installmentsToken": "bc1a1923-fadc-427b-b014-e43eb4462e81",
  "creationDate": "2025-01-29T23:53:52.7150456+00:00",
  "expirationDate": "2025-01-30T00:03:52.71509+00:00",
  "currency": "MXN",
  "amount": 1000,
  "installments": [
        {
            "installments": 3,
            "installmentAmount": 448.98,
            "totalPaymentAmount": 1346.95,
            "financingFee": 346.95
        },
        {
            "installments": 6,
            "installmentAmount": 275.68, 
            "totalPaymentAmount": 1654.12, 
            "financingFee": 654.12
        }
    ]
}
```

### 关键响应字段

| 参数 | 描述 | 用例 |
| - | - | - |
| `installmentsToken` | 用于标识分期付款报价的唯一令牌 | 处理所选分期付款计划时必需。 |
| `creationDate` | 生成报价时的时间戳。 | 跟踪报价的有效性和时间。 |
| `expirationDate` | 报价到期时的时间戳。 | 确保客户在到期前选择计划。 |
| `currency` | 交易货币。 | 向客户显示正确的货币符号。 |
| `installments` | 可用分期付款选项的数组。 | 向客户展示多种付款计划。 |
| `installments.installments` | 按月付款的期数。 | 显示付款期限时长。 |
| `installments.installmentAmount` | 每月付款金额。 | 向客户显示每月费用。 |
| `installments.totalPaymentAmount` | 包含费用在内的总金额。 | 显示融资的全部成本。 |
| `installments.financingFee` | 融资总成本。 | 单独显示费用和利息。 |

### 错误响应

分期付款报价生成失败时：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "status": {
    "code": "300",
    "detail": "Instalment Payment Plan is only for types of Credit Card methods"
  }
}
```

### 分期付款展示最佳实践

* 清晰显示所有费用（融资费用、总金额）
* 突出显示每月付款金额
* 包含不同分期付款选项之间的比较
* 说明后续分期付款的自动付款流程
* 提供客户支持信息
* 妥善处理令牌过期（**10 分钟有效期**）

***

## 步骤 3：处理分期付款

客户选择分期付款计划后，使用分期付款令牌处理付款。

### 示例请求

```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/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1600",
        "flow": "DIRECT"
    },
    "externalId": "dffbd2a6-6e65-469b-8bbe-dac269882220",
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "RFC",
            "id": "XXX840510XX1"
        },
        "email": "mail@company.com"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "YYY180222YY6"
        },
        "email": "john.doe@example.com"
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029",
        "installments": 3,
        "installmentsToken": "bc1a1923-fadc-427b-b014-e43eb4462e81"
    }
}'
```

***

## 步骤 4：跟踪分期付款状态

您可以通过以下方式监控分期付款计划的进度：

> [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 为分期付款计划和付款提供多种状态码。

| 代码 | 状态 | 描述 |
| :- | :- | :- |
| `103` | `APPROVED` | 付款已确认，但尚未到账。 |
| `200` | `Completed` | 付款已完成。 |
| `811` | `Rejected` | 请求金额高于或低于允许的最大/最小值。 |

> [!NOTE]
>
> **APPROVED 不是最终状态。** 它表示银行卡付款已确认，但资金尚未计入您的余额。您可以看到该付款，但在状态变为 Completed 之前无法提取资金。这通常需要 1 到 2 天，具体取决于服务商。

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

***

## 步骤 5：管理分期付款生命周期

### 分期付款流程

```mermaid theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'actorBkg': '#31467c', 'actorBorder': '#0c1a29', 'actorTextColor': '#ffffff', 'actorLineColor': '#0c1a29', 'signalColor': '#0c1a29', 'signalTextColor': '#0c1a29', 'labelBoxBkgColor': '#31467c', 'labelBoxBorderColor': '#0c1a29', 'labelTextColor': '#ffffff', 'loopTextColor': '#0c1a29', 'noteBkgColor': '#ffffff', 'noteBorderColor': '#31467c', 'noteTextColor': '#0c1a29'}}}%%
sequenceDiagram
    participant C as 客户
    participant M as 商户
    participant LP as Localpayment
    participant B as 银行
    
    C->>M: 发起带分期选项的支付
    M->>LP: 请求分期报价
    LP->>M: 返回 installmentsToken 和分期选项
    M->>C: 展示分期方案
    C->>M: 选择偏好的方案
    M->>LP: 使用 installmentsToken 处理支付
    LP->>B: 授权首期分期
    B->>LP: 授权已确认
    LP->>M: 支付确认
    M->>C: 显示支付结果（已批准/已拒绝）
    Note over C: 客户收到交易状态和分期方案详情
    Note over LP: 每月分期自动处理
    LP->>M: 每期分期的 Webhook
```

***

## 测试您的集成

### 测试场景

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

1. **分期付款成功**：完成分期付款流程
2. **多种计划选项**：展示不同的分期期限（2、3、6 个月）
3. **令牌过期**：处理已过期的 installmentsToken（10 分钟有效期）
4. **状态更新**：Webhook 处理和状态轮询。

***

## 后续步骤

实施分期付款后，请考虑以下附加功能：

> [card] [退款](https://docs.localpayment.com/zh/docs/refund-card-payment)
>
> 如有必要，您可以将款项退还给客户。详情请参阅相关文档。

> [card] [查看交易详情](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 您可以使用 Localpayment API 获取交易信息，以获得更详细的分析。


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