# 支付服务 API 文档

**服务**: `hl-payment-service`
**接口总数**: 7

## 目录

- **支付管理** (7 个接口)

---

## 支付管理

### `GET` /admin/payment/list

**支付交易列表**

分页查询支付交易记录，支持按订单号、交易状态、交易类型筛选

**关联字典**：
- payment_mode：支付模式（列表筛选+显示）

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `endDate` | `string` |  | 结束日期 | 2026-12-31 |
| `mchId` | `string` |  | 商户号 | 1246532201 |
| `orderNo` | `string` |  | 订单编号 | HL20260301120000001234 |
| `page` | `integer(int32)` |  | 页码 | 1 |
| `pageSize` | `integer(int32)` |  | 每页条数 | 20 |
| `startDate` | `string` |  | 开始日期 | 2026-01-01 |
| `status` | `string` |  | 支付状态 | SUCCESS |
| `tradeType` | `string` |  | 交易类型: JSAPI/H5 | JSAPI |

**响应** `统一响应结果«分页结果«支付交易信息»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«支付交易信息»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `支付交易信息[]` |  | 数据列表 |
|     `createTime` | `string` |  | 创建时间 |
|     `mchId` | `string` |  | 商户号 |
|     `orderId` | `long` |  | 订单ID |
|     `orderNo` | `string` |  | 订单编号 |
|     `outTradeNo` | `string` |  | 商户订单号 |
|     `payTime` | `string` |  | 支付时间 |
|     `payType` | `string` |  | 支付类型: FULL/DEPOSIT/BALANCE |
|     `status` | `string` |  | 交易状态 |
|     `totalAmount` | `number` |  | 交易金额 |
|     `tradeType` | `string` |  | 交易类型: JSAPI/H5 |
|     `transactionId` | `long` |  | 交易ID |
|     `transactionIdWx` | `string` |  | 微信支付交易号 |
|     `userId` | `long` |  | 用户ID |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/payment/order/{orderId}

**按订单查询交易**

查询指定订单的所有支付交易记录

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `orderId` | `integer` |  | 订单ID |

**响应** `统一响应结果«List«支付交易信息»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `支付交易信息[]` |  | 响应数据 |
|   `createTime` | `string` |  | 创建时间 |
|   `mchId` | `string` |  | 商户号 |
|   `orderId` | `long` |  | 订单ID |
|   `orderNo` | `string` |  | 订单编号 |
|   `outTradeNo` | `string` |  | 商户订单号 |
|   `payTime` | `string` |  | 支付时间 |
|   `payType` | `string` |  | 支付类型: FULL/DEPOSIT/BALANCE |
|   `status` | `string` |  | 交易状态 |
|   `totalAmount` | `number` |  | 交易金额 |
|   `tradeType` | `string` |  | 交易类型: JSAPI/H5 |
|   `transactionId` | `long` |  | 交易ID |
|   `transactionIdWx` | `string` |  | 微信支付交易号 |
|   `userId` | `long` |  | 用户ID |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/payment/refund/order/{orderId}

**按订单查询退款**

查询指定订单的所有退款记录

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `orderId` | `integer` |  | 订单ID |

**响应** `统一响应结果«List«退款记录信息»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `退款记录信息[]` |  | 响应数据 |
|   `createTime` | `string` |  | 创建时间 |
|   `mchId` | `string` |  | 商户号 |
|   `orderId` | `long` |  | 订单ID |
|   `orderNo` | `string` |  | 订单编号 |
|   `outRefundNo` | `string` |  | 商户退款单号 |
|   `reason` | `string` |  | 退款原因 |
|   `refundAmount` | `number` |  | 退款金额 |
|   `refundId` | `long` |  | 退款ID |
|   `refundIdWx` | `string` |  | 微信退款单号 |
|   `status` | `string` |  | 退款状态 |
|   `successTime` | `string` |  | 退款成功时间 |
|   `totalAmount` | `number` |  | 订单总金额 |
|   `transactionId` | `long` |  | 交易ID |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/payment/refund/{refundId}

**退款详情**

获取单笔退款记录的完整信息，包含微信退款单号和退款状态

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `refundId` | `integer` |  | 退款ID |

**响应** `统一响应结果«退款记录信息»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `退款记录信息` |  | 响应数据 |
|   `createTime` | `string` |  | 创建时间 |
|   `mchId` | `string` |  | 商户号 |
|   `orderId` | `long` |  | 订单ID |
|   `orderNo` | `string` |  | 订单编号 |
|   `outRefundNo` | `string` |  | 商户退款单号 |
|   `reason` | `string` |  | 退款原因 |
|   `refundAmount` | `number` |  | 退款金额 |
|   `refundId` | `long` |  | 退款ID |
|   `refundIdWx` | `string` |  | 微信退款单号 |
|   `status` | `string` |  | 退款状态 |
|   `successTime` | `string` |  | 退款成功时间 |
|   `totalAmount` | `number` |  | 订单总金额 |
|   `transactionId` | `long` |  | 交易ID |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/payment/{orderId}/refund

**发起退款**

退款流程：验证订单 → 查找原支付交易 → 调用微信退款API → 记录退款单 → 等待微信回调更新状态

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `orderId` | `integer` |  | 订单ID |

**请求体** `退款请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `amount` | `number` | 是 | 退款金额 |
| `orderId` | `long` | 是 | 订单ID |
| `reason` | `string` |  | 退款原因 |

**响应** `统一响应结果«退款记录信息»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `退款记录信息` |  | 响应数据 |
|   `createTime` | `string` |  | 创建时间 |
|   `mchId` | `string` |  | 商户号 |
|   `orderId` | `long` |  | 订单ID |
|   `orderNo` | `string` |  | 订单编号 |
|   `outRefundNo` | `string` |  | 商户退款单号 |
|   `reason` | `string` |  | 退款原因 |
|   `refundAmount` | `number` |  | 退款金额 |
|   `refundId` | `long` |  | 退款ID |
|   `refundIdWx` | `string` |  | 微信退款单号 |
|   `status` | `string` |  | 退款状态 |
|   `successTime` | `string` |  | 退款成功时间 |
|   `totalAmount` | `number` |  | 订单总金额 |
|   `transactionId` | `long` |  | 交易ID |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/payment/{transactionId}

**交易详情**

获取单笔交易的完整信息，包含微信支付流水号

**关联字典**：
- payment_mode：支付模式（显示）

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `transactionId` | `integer` |  | 交易ID |

**响应** `统一响应结果«支付交易信息»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `支付交易信息` |  | 响应数据 |
|   `createTime` | `string` |  | 创建时间 |
|   `mchId` | `string` |  | 商户号 |
|   `orderId` | `long` |  | 订单ID |
|   `orderNo` | `string` |  | 订单编号 |
|   `outTradeNo` | `string` |  | 商户订单号 |
|   `payTime` | `string` |  | 支付时间 |
|   `payType` | `string` |  | 支付类型: FULL/DEPOSIT/BALANCE |
|   `status` | `string` |  | 交易状态 |
|   `totalAmount` | `number` |  | 交易金额 |
|   `tradeType` | `string` |  | 交易类型: JSAPI/H5 |
|   `transactionId` | `long` |  | 交易ID |
|   `transactionIdWx` | `string` |  | 微信支付交易号 |
|   `userId` | `long` |  | 用户ID |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/payment/{transactionId}/sync

**同步支付状态**

主动查询微信支付状态并同步本地数据，适用于回调未到达的场景

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `transactionId` | `integer` |  | 交易ID |

**响应** `统一响应结果«支付交易信息»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `支付交易信息` |  | 响应数据 |
|   `createTime` | `string` |  | 创建时间 |
|   `mchId` | `string` |  | 商户号 |
|   `orderId` | `long` |  | 订单ID |
|   `orderNo` | `string` |  | 订单编号 |
|   `outTradeNo` | `string` |  | 商户订单号 |
|   `payTime` | `string` |  | 支付时间 |
|   `payType` | `string` |  | 支付类型: FULL/DEPOSIT/BALANCE |
|   `status` | `string` |  | 交易状态 |
|   `totalAmount` | `number` |  | 交易金额 |
|   `tradeType` | `string` |  | 交易类型: JSAPI/H5 |
|   `transactionId` | `long` |  | 交易ID |
|   `transactionIdWx` | `string` |  | 微信支付交易号 |
|   `userId` | `long` |  | 用户ID |
| `message` | `string` |  | 响应消息 |

---