> ## 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.

# 取消付款

有时您需要在付款发起后将其停止，本指南介绍取消流程。

如果您因错误或需求变更需要取消付款，只要该付款处于以下状态之一，即可取消：**待授权（Pending Authorization）**、**已接收（Received）**、**暂挂（On Hold）** 或 **已锁定（Locked）**。

您可以通过[Business Portal 网站](https://docs.localpayment.com/zh/docs/dashboard-review-payout.md)取消付款，也可以通过 API 以编程方式取消付款。

## 先决条件

取消付款之前，请确保您已具备以下条件：

* 一笔**处于活动状态的付款交易**，其状态为：`PendingAuth`、`Received`、`OnHold` 或 `Locked`
* 具有适当权限的有效 API 凭证
* 交易标识符（`externalId`）

> [!WARNING]
>
> **重要的**
>
> 付款一旦进入 **处理中（Processing）** 或 **已完成（Completed）** 状态，就无法通过 API 取消。如需协助处理已处理的交易，请联系支持团队。

***

## API endpoint

要取消付款，请向[取消付款](https://docs.localpayment.com/zh/reference/void-a-payout.md)endpoint 发送 `PATCH` 请求。

### 取消付款请求

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
PATCH https://api.stage.localpayment.com/api/payout/cancel
```

### 验证

请在请求头中包含您的访问令牌：

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
Authorization: Bearer <your_access_token>
```

### 关键请求参数

| 参数 | 类型 | 描述 | 必需的 |
| - | - | - | - |
| `externalId` | string | 您系统中的唯一交易标识符 | ✅ |

### 示例请求

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request PATCH \
     --url https://api.stage.localpayment.com/api/payout/cancel \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
       "externalId": "a971b7ee-fe47-4112-81fc-484f8e5c64d7"
     }'
```

***

## 响应处理

### 成功响应

取消成功后，您将收到包含更新后状态的响应：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "a971b7ee-fe47-4112-81fc-484f8e5c64d7",
  "internalId": "3d36811d-1c02-41ea-a576-68df62c4603a",
  "status": {
    "code": "900",
    "description": "Cancelled",
    "detail": "The payout was cancelled successfully"
  }
}
```

#### 关键响应字段

| 字段 | 类型 | 描述 |
| - | - | - |
| `externalId` | string | 您系统中的交易标识符 |
| `internalId` | string | Localpayment 的内部交易 ID |
| `status.code` | string | 状态代码（900 = 已取消） |
| `status.description` | string | 人类可读的状态描述 |
| `status.detail` | string | 有关取消的更多详情 |

### 错误响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "Status": 404,
  "Message": "This transaction does not exist.",
  "TraceId": "dae2d1cb-7e9e-48a5-8530-980f38b31712"
}
```

***

## 实施最佳实践

* 在尝试取消之前，务必先验证交易状态
* 所有 API 请求均使用 HTTPS
* 妥善保管访问令牌并定期轮换使用
* 实施适当的错误处理和重试逻辑
* 记录所有取消尝试以便审计

***

## 测试您的实施

在部署到生产环境之前，请彻底测试您的取消逻辑：

1. **使用有效交易进行测试**，交易需处于可取消状态
2. **使用无效交易进行测试**，以便妥善处理错误
3. **测试身份验证失败**和令牌过期的情况
4. **如已实施，请验证 webhook 处理**
5. **测试速率限制**和重试逻辑

***

## 资源与后续步骤

利用这些关键资源，最大限度地提高您的集成成功率。

> [card] [Webhook 集成](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 设置交易状态更新的实时通知。

> [card] [报告 Business Portal](https://docs.localpayment.com/zh/docs/balance-report.md)
>
> 获取详细的分析、报告工具和对账功能。

> [card] [交易监控](https://docs.localpayment.com/zh/reference/transaction-status-error-codes)
>
> 学习查询交易状态并实现全面跟踪。

> [card] [API 参考](https://docs.localpayment.com/zh/reference/exchange-bulk.md)
>
> 提供包含交互式示例的完整 endpoint 文档。

> [!NOTE]
>
> **专业提示**
>
> 在部署到生产环境之前，务必先在我们的沙盒环境中测试您的工作流程。这可以确保您的错误处理、Webhook 处理和状态跟踪在所有场景下都能正常工作。

***

> [!NOTE]
>
> **需要帮助吗？**
>
> 如果您遇到任何问题或需要集成方面的帮助，请联系[我们的支持团队](mailto:support@localpayment.com)。


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