hostingpay-query-trade-close.md

## 目录

- [接口概述](#接口概述)
- [应用场景](#应用场景)
- [SDK 映射](#sdk-映射)
- [公共请求参数](#公共请求参数)
- [请求参数 data](#请求参数-data)
- [请求示例](#请求示例)
- [同步返回参数](#同步返回参数)
- [异步返回参数](#异步返回参数)
- [业务返回码](#业务返回码)
- [文档勘误与实现备注](#文档勘误与实现备注)

# 托管交易关单

> 本文依据 2025-01-03 官方文档整理，适用于 `v2/trade/hosting/payment/close`。

## 接口概述

| 属性 | 值 |
|------|-----|
| 请求方式 | `POST` |
| 汇付 API 端点 | `https://api.huifu.com/v2/trade/hosting/payment/close` |
| SDK Request 类 | `V2TradeHostingPaymentCloseRequest` |
| Content-Type | `application/json;charset=UTF-8` |

说明：

- 支持 JSON 报文。
- 请求整体需要签名，验签规则见 `references/hostingpay-java-tech-spec.md`。
- 适用于微信、支付宝、云闪付交易；快捷网银待后续支持。
- 关单只适用于未支付成功的订单，已支付成功订单需要走退款流程。

## 应用场景

- 托管支付订单长时间未支付，需要主动关闭订单时使用。
- 业务侧取消订单，需阻止后续继续支付时使用。

## SDK 映射

`V2TradeHostingPaymentCloseRequest` 的独立 setter 字段：

| 字段 | setter | 类型 | 必填 | 说明 |
|------|--------|------|------|------|
| reqSeqId | `setReqSeqId()` | String(64) | Y | 本次关单请求流水号，同一 `huifu_id` 下当天唯一 |
| reqDate | `setReqDate()` | String(8) | Y | 本次关单请求日期，`yyyyMMdd` |
| huifuId | `setHuifuId()` | String(32) | Y | 商户号 |
| orgReqDate | `setOrgReqDate()` | String(8) | Y | 原请求日期，`yyyyMMdd` |
| orgReqSeqId | `setOrgReqSeqId()` | String(64) | Y | 原请求流水号 |

说明：

- 当前官方请求参数表只列出了以上 5 个字段。
- 历史版本文档曾将 `notify_url` 视为可选扩展字段，但本次官方页面请求参数表未列出该字段；本文不将其视为稳定请求参数。

## 公共请求参数

| 参数 | 中文名 | 类型 | 长度 | 必填 | 说明 |
|------|--------|------|------|------|------|
| sys_id | 系统号 | String | 32 | Y | 渠道商/商户的 `huifu_id`；渠道商主体传渠道商号，直连商户主体传商户号 |
| product_id | 产品号 | String | 32 | Y | 汇付分配的产品号 |
| sign | 加签结果 | String | 512 | Y | 对整个请求报文签名 |
| data | 请求数据 | JSON | - | Y | 业务请求参数 |

> 强制请求头约束：
> - 必须带 `jpt-x-skill-source: <skill_source>`
> - 如果当前按 PHP 接入，由于本页请求 `data` 明确包含 `huifu_id`，还必须带 `jpt-x-skill-huifu_id: <data.huifu_id>`
> - 当前 Skill 包对齐的官方 PHP SDK 主链路在 `MerConfig.skill_source` 已配置时，会自动带 `jpt-x-skill-source`，并在当前请求 `huifu_id` 存在且非空时自动带 `jpt-x-skill-huifu_id`
> - 当前 Java SDK 基线也会在请求 `data` 明确包含 `huifu_id` 时自动带 `jpt-x-skill-huifu_id: <data.huifu_id>`
> - 这两项属于 HTTP 请求头，不要误写进 `data`；完整口径见 `references/shared-request-header-policy.md`

## 请求参数 data

| 参数 | 中文名 | 类型 | 长度 | 必填 | 说明 |
|------|--------|------|------|------|------|
| req_seq_id | 请求流水号 | String | 64 | Y | 同一 `huifu_id` 下当天唯一 |
| req_date | 请求日期 | String | 8 | Y | `yyyyMMdd` |
| huifu_id | 商户号 | String | 32 | Y | 开户自动生成 |
| org_req_date | 原请求日期 | String | 8 | Y | `yyyyMMdd` |
| org_req_seq_id | 原请求流水号 | String | 64 | Y | 原交易请求流水号 |

## 请求示例

> 官方页面未提供请求示例，以下示例按参数表整理。

```json
{
  "sys_id": "6666000108840829",
  "product_id": "YYZY",
  "data": {
    "req_seq_id": "20240515101010868close001",
    "req_date": "20240515",
    "huifu_id": "6666000109133323",
    "org_req_date": "20240514",
    "org_req_seq_id": "20240514165442868h32ss2g3s7vnxq"
  },
  "sign": "<SDK_AUTOGENERATED_SIGNATURE>"
}
```

## 同步返回参数

### 公共返回参数

| 参数 | 中文名 | 类型 | 长度 | 必填 | 说明 |
|------|--------|------|------|------|------|
| sign | 签名 | String | 512 | Y | 对响应整体签名 |
| data | 响应内容体 | JSON | - | N | 业务返回参数 |

### data

| 参数 | 中文名 | 类型 | 长度 | 必填 | 说明 |
|------|--------|------|------|------|------|
| resp_code | 业务响应码 | String | 8 | Y | 业务响应码 |
| resp_desc | 业务响应信息 | String | 512 | Y | 业务返回描述 |
| req_seq_id | 请求流水号 | String | 64 | Y | 关单请求时传入，原样返回 |
| req_date | 请求日期 | String | 8 | Y | 关单请求时传入，原样返回 |
| huifu_id | 商户号 | String | 32 | Y | 商户号 |
| org_req_date | 原请求日期 | String | 8 | Y | `yyyyMMdd` |
| org_req_seq_id | 原请求流水号 | String | 64 | Y | 原请求流水号 |
| org_trans_stat | 原交易状态 | String | 1 | N | `P`=处理中，`S`=成功，`F`=失败 |
| close_stat | 关单状态 | String | 1 | Y | `P`=处理中，`S`=成功，`F`=失败 |

### 同步成功示例

> 官方页面未提供成功示例，以下示例按参数表整理。

```json
{
  "data": {
    "resp_code": "00000000",
    "resp_desc": "交易成功",
    "req_seq_id": "20240515101010868close001",
    "req_date": "20240515",
    "huifu_id": "6666000109133323",
    "org_req_date": "20240514",
    "org_req_seq_id": "20240514165442868h32ss2g3s7vnxq",
    "org_trans_stat": "F",
    "close_stat": "S"
  }
}
```

## 异步返回参数

> 关单结果通过异步通知返回；异步回调体为 `resp_data`。

### resp_data

| 参数 | 中文名 | 类型 | 长度 | 必填 | 说明 |
|------|--------|------|------|------|------|
| resp_code | 业务响应码 | String | 8 | Y | 业务响应码 |
| resp_desc | 业务响应信息 | String | 512 | Y | 业务返回描述 |
| huifu_id | 商户号 | String | 32 | Y | 商户号 |
| org_req_date | 原请求日期 | String | 8 | Y | `yyyyMMdd` |
| org_req_seq_id | 原请求流水号 | String | 64 | Y | 原请求流水号 |
| org_trans_stat | 原交易状态 | String | 1 | N | `P`=处理中，`S`=成功，`F`=失败 |
| close_stat | 关单状态 | String | 1 | Y | `S`=成功，`F`=失败 |

## 业务返回码

| 返回码 | 返回描述 |
|--------|----------|
| 00000000 | 交易成功 |
| 00000100 | 交易处理中 |
| 10000000 | 无效参数 |
| 99999999 | 系统异常，请稍后重试 |
| 99010003 | 交易不存在 |
| 30000001 | 原交易已经终态，不允许关单 |
| 30000001 | 关单状态为终态，不能重复关单 |

## 文档勘误与实现备注

- 本次官方页面没有提供请求示例和返回示例；本文中的示例按参数表和历史版本样例整理，仅用于说明字段组织方式。
- 官方页面给出了异步返回参数 `resp_data`，但请求参数表中没有列出 `notify_url` 或其他回调地址字段；历史版本文档曾将 `notify_url` 视为扩展字段，本文不将其视为稳定官方参数。
- 业务返回码 `30000001` 在官方表格里重复出现两次，分别对应“原交易已经终态，不允许关单”和“关单状态为终态，不能重复关单”；调用方需要结合 `resp_desc` 区分。
- 关单同步返回里的 `close_stat` 包含 `P/S/F`，异步返回里的 `close_stat` 只列出 `S/F`；不要混用两套状态机。