---
url: /docs/api-docs/v1/admin/withdrawals.md
---
# withdrawal — 提现审批（6 action）

> 前缀：`/api/v1/admin/withdrawal/`
> 权限：`WITHDRAWAL_READ`（list/detail）· `WITHDRAWAL_APPROVE`（approve/reject/payout/recall）— 仅 **super + operator**，it 一律 403
> 代码：`src/app/admin/interface/api/withdrawal_mgmt.py` + `application/usecase/withdrawal_mgmt.py`

## 3.6.1 list —— 提现列表

`GET /api/v1/admin/withdrawal/list` · 权限 `WITHDRAWAL_READ`

**Query 参数**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `page` | int | ⬜ | 1 | ≥1 |
| `page_size` | int | ⬜ | 20 | 1~100 |
| `status` | string | ⬜ | — | 提现状态过滤 |
| `user_id` | string | ⬜ | — | 按用户过滤 |
| `date_from` / `date_to` | string | ⬜ | — | ISO 日期区间 |

**响应 data**：`{ total, page, page_size, items: [WithdrawalSummary] }`

`WithdrawalSummary` 字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` / `user_id` | string | 提现单 / 用户 |
| `amount` | float | 金额 |
| `status` | string | `pending` | `approved` | `rejected` | `paid` | `recalled` |
| `payment_reference` | string | null | 打款凭证号 |
| `payment_channel` | string | null | 打款渠道 |
| `created_at` / `updated_at` | string | ISO |

**错误码**：`40201001` page/page\_size < 1。

## 3.6.2 detail —— 提现详情

`GET /api/v1/admin/withdrawal/detail/{withdrawal_id}` · 权限 `WITHDRAWAL_READ`

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `withdrawal` | object | 全字段 |
| `user` | object | 用户摘要 |
| `bank_info` | object | 收款信息 |
| `audit_trail` | array | 审批轨迹 |

**错误码**：`40201401`（404）提现单不存在。

## 3.6.3 approve —— 审批通过

`POST /api/v1/admin/withdrawal/approve` · 权限 `WITHDRAWAL_APPROVE`

**请求 body**：`{ withdrawal_id✅, note? }`

**响应 data**：`{ "success": true, "approved_at": "<ISO>" }`

**错误码**：`40201401`（404）· `40201402` 状态不允许审批（含重复审批）· `40201001` 参数非法。

## 3.6.4 reject —— 审批拒绝

`POST /api/v1/admin/withdrawal/reject` · 权限 `WITHDRAWAL_APPROVE`

**请求 body**：`{ withdrawal_id✅, reason✅, note? }`

**响应 data**：`{ "success": true }`

**错误码**：`40201401`（404）· `40201402` 状态不允许 · `40201001` reason 缺失。

## 3.6.5 payout —— 打款（⚠️ 最敏感）

`POST /api/v1/admin/withdrawal/payout` · 权限 `WITHDRAWAL_APPROVE` · **confirm\_text = `"PAYOUT"`**

**请求 body**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `withdrawal_id` | string | ✅ | 提现单 |
| `payment_reference` | string | ✅ | 打款凭证号（银行/渠道流水号） |
| `confirm_text` | string | ✅ | **必须逐字为 `"PAYOUT"`**，否则 `40201001`（400） |

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `success` | bool | 恒 true |
| `paid_at` | string | ISO 打款时间 |
| `payment_channel` | string | 打款渠道 |

**错误码**：

| code | 场景 |
|---|---|
| `40201401` | 提现单不存在（404） |
| `40201402` | 状态不允许打款 |
| `40201403` | 重复打款（DUPLICATE\_PAYOUT） |
| `40201404` | 支付渠道故障 |
| `40201405` | 银行账户信息不一致 |
| `40201406` | 单日打款金额超上限 |
| `40201001` | confirm\_text 不匹配 / payment\_reference 缺失 |

## 3.6.6 recall —— 追回

`POST /api/v1/admin/withdrawal/recall` · 权限 `WITHDRAWAL_APPROVE`

**请求 body**：`{ withdrawal_id✅, reason✅ }`

**响应 data**：`{ "success": true, "recalled_at": "<ISO>" }`

**错误码**：`40201401`（404）· `40201402` 状态不允许 · `40201001` 参数非法。

***

**本域错误码汇总**：`40201401`-`40201406`（§6.6）。验收链路（§7.5）：`approve → payout → notification`。通用失败见 [admin 总览](/api-docs/v1/admin/)。