> ## 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 使您能够处理银行卡支付的退款，您可以通过 API 集成和 Business Portal 界面将款项退回到客户的信用卡或借记卡。本指南涵盖了银行卡交易的完整退款流程。

## 开始之前

请确保您已备好：

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

### 其他退款要求：

* 您的Localpayment账户余额足以支付退款金额。
* 具有退款权限的用户角色（请参阅[用户角色](https://docs.localpayment.com/zh/docs/user-roles-and-permissions.md)文档）。
* 原始交易必须处于 `Completed` 状态。
* 原始支付交易的 `externalId`。

***

## 实施指南

Localpayment 提供两种处理信用卡退款的方法：API 集成用于自动处理，Business Portal 用于手动操作。

> [card] [API退款处理](https://docs.localpayment.com/zh/reference/refund-a-payin.md)
>
> 通过 REST API 以编程方式处理退款，实现自动化工作流程并与您的系统集成。

> [card] [Business Portal 退款处理](https://docs.localpayment.com/zh/docs/dashboard-create-manual-refund.md)
>
> 通过 Localpayment Business Portal 手动处理退款，该门户网站拥有用户友好的界面。

***

## 信用卡支付直接退款

对于银行卡交易，退款将作为**直接退款**处理，即您只需提供原始交易的 `externalId`。由于资金会退回到支付时使用的原卡，因此无需提供额外的收款人或银行信息。

***

## 步骤 1：通过 API 处理退款

要通过 API 退还银行卡付款，请向[退款](https://docs.localpayment.com/zh/reference/refund-a-payin.md)endpoint 发送 `PATCH` 请求。

### 关键请求参数

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

| 参数 | 说明 | 必需的 |
| - | - | - |
| `externalId` | 原始交易的 externalId。 | ✅ |

### 示例请求

以下是使用 `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/{{externalId}}/refund' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --data '{
    "comment": "Refund API Credit Card"
  }'
```

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

***

## 步骤 2：处理响应

### 成功响应

成功处理的退款确认详情：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "d260ae17-0978-4429-bda1-8dfed9da6c6b",
  "internalId": "53c91969-147e-4273-a659-ee5012ce9c83",
  "status": {
    "code": "902",
    "description": "REFUNDED",
    "detail": "The payin was refunded"
  }
}
```

### 关键响应字段

| 参数 | 说明 | 用例 |
| - | - | - |
| `externalId` | 您在原始交易中的参考编号。 | 对账和跟踪。 |
| `internalId` | Localpayment的唯一退款标识符。 | 用于支持和审计目的。 |
| `status.code` | 退款状态代码（`902` 表示退款成功）。 | 状态监控。 |

### 错误响应

退款申请失败时，您将收到错误信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "status": {
    "code": "400",
    "description": "ERROR",
    "detail": "Invalid operation"
  }
}
```

### 常见错误场景

| 错误 | 说明 | 解决方案 |
| - | - | - |
| 资金不足 | 您的Localpayment账户余额不足以支付退款金额。 | 向您的 Localpayment 账户充值，或等待待结算款项到账。 |
| 未找到交易 | 提供的 `externalId` 不存在或无效 | 请确认 externalId 是否正确，以及该交易是否存在于您的交易历史记录中。 |
| 无效状态 | 原始交易不属于可退款状态（必须为 `Completed`） | 请先查看交易状态，确保交易已成功处理后再尝试退款。 |
| 没有权限 | 您的用户角色缺少必要的退款权限 | 请联系您的账户管理员，以获取您角色所需的相应退款权限。 |
| 重复退款 | 尝试对已退款的交易进行退款 | 通过查看退款状态来确认该交易之前是否已被退款。 |
| 无效金额 | 尝试在只允许全额退款的情况下进行部分退款。 | 仅处理全额交易金额的退款。 |

***

## Business Portal 退款

信用卡退款也可以通过LocalpaymentBusiness Portal 界面进行处理。这种方法提供了一个可视化的退款管理工作流程，尤其适用于以下情况：

* 偶尔会出现不需要 API 自动化处理的**退款情况**。
* 在需要审批流程的地方进行**行政监督**。
* 无需开发资源即可**快速处理退款**。

有关通过 Business Portal 处理退款的详细说明，包括分步指南和界面演示，请参阅[Business Portal 退款指南](https://docs.localpayment.com/zh/docs/dashboard-create-manual-refund.md)。

> [!WARNING]
>
> **需要审批**：
>
> 所有通过 Localpayment Business Portal 发起的退款都需要经过指定的授权流程才能获得批准。请确保您拥有必要的用户权限后再尝试通过 Business Portal 进行退款。

***

## 步骤 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` | 由于验证错误或参数无效，退款申请失败。 |
| `902` | `REFUNDED` | 款项已成功退还。 |

> [!NOTE]
>
> **退款不会立即到达客户账户。** 您发起退款后，退款金额可能需要几天时间才会显示在客户的银行卡账单上。具体时间取决于支付服务商和发卡机构。

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

***

## 测试您的集成

### 测试场景

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

1. **退款成功**：使用有效的 `externalId` 并在资金充足的情况下处理退款。
2. **资金不足**：尝试退款但账户余额不足。
3. **无效交易**：尝试对不存在的 `externalId` 退款。
4. **重复退款**：尝试对已退款的交易进行退款。
5. **权限验证**：使用具有不同权限级别的用户进行测试。

***

## 后续步骤

> [card] [查看交易状态](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 使用交易状态
> API 查看交易和退款的当前状态。

> [card] [配置 Webhook](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 设置
> Webhook 以接收退款状态变更的实时通知。

> [card] [审核用户角色](https://docs.localpayment.com/zh/docs/user-roles-and-permissions.md)
>
> 管理退款处理功能的用户权限和角色。


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