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

# 取消 APM 付款

Localpayment 允许您通过 API 集成取消待处理的 APM 付款。本指南涵盖了使用直接取消方法取消 APM 交易的完整工作流程，该方法仅需要交易的 externalId。

## 开始之前

请确保您已备好：

> [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/docs/user-roles-and-permissions.md)文档）。
* 原始交易必须处于可取消状态。
* 您要取消的 APM 付款交易的 `externalId`。
* 提供完整的受益人信息，以便进行数据必要的退款。

***

## APM 付款的直接取消

APM 付款的取消按**直接取消**处理，这意味着您只需提供原始交易的 `externalId`，并将 `status` 参数设置为 `CANCELLED`。系统会立即停止对该付款的任何后续处理。

> [!WARNING]
>
> **重要的**
>
> APM 付款只能在待处理或进行中状态下取消。一旦 APM 付款完成或结算，您必须办理退款，而不能取消。

***

## 步骤 1：通过 API 取消 APM 付款

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

### 关键请求参数

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

| 参数 | 描述 | 必需的 |
| - | - | - |
| `externalId` | 原始交易的 externalId | ✅ |
| `status` | 必须设置为 `CANCELLED` 才能发起取消 | ✅ |

### 示例请求

以下是使用 `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/transactions/{{externalId}}/status' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "CANCELLED"
  }'
```

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

***

## 步骤 2：处理响应

### 成功响应

成功取消的 APM 付款将返回确认详情：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "1c364061-1f3d-4b94-c270-bf915c22e8f5",
  "internalId": "8a9abd31-31e0-429a-32a6-cca8b9e1e536",
  "status": {
    "code": "900",
    "description": "CANCELLED",
    "detail": "The payin was cancelled"
  }
}
```

### 关键响应字段

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

### 错误响应

取消请求失败时，您将收到错误信息：

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

### 常见错误场景

| 错误 | 描述 | 解决方案 |
| - | - | - |
| 未找到交易 | 所提供的 `externalId` 不存在或无效 | 请确认 externalId 是否正确，以及该交易是否存在于您的交易历史记录中。 |
| 无效状态 | 原始交易不处于可取消状态 | 在尝试取消之前，请检查交易状态，并确保其仍处于待处理或进行中状态 |
| 没有权限 | 您的用户角色缺少必要的退款权限 | 请联系您的账户管理员，以获取您角色所需的相应退款权限。 |
| 已完成 | 该交易已完成，无法取消 | 对于已完成的交易，请办理退款而不是取消 |
| 无效参数 | `status` 参数缺失或未设置为 `CANCELLED` | 请确保请求正文严格按照规定包含 `{"status": "CANCELLED"}` |

***

## 步骤 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` | 由于验证错误或参数无效，取消请求失败。 |
| `900` | `CANCELLED` | 该收款已成功取消。 |

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

***

## 测试您的集成

### 测试场景

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

1. **取消成功**：使用有效的 externalId 取消待处理的 APM 付款。
2. **无效交易**：尝试取消不存在的 externalId。
3. **已完成**：尝试取消已完成的交易。
4. **权限验证**：使用具有不同权限级别的用户进行测试。
5. **缺少状态参数**：尝试在没有必填的 status 字段的情况下取消。

***

## 后续步骤

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

> [card] [处理退款](https://docs.localpayment.com/zh/docs/refund-apm-payment.md)
>
> 了解如何为无法取消的已完成 APM 付款处理退款。


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