# 免确认收款授权（transfer-auth 族）

> 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:全部 Bearer | [← 返回 API 索引](../README.md)
>
> 集成实现:见 [integrations/wxpay](../../integrations/wxpay.md)（微信 V3 免确认收款授权）。

开启一次后，后续提现走免确认转账直接到账，不再跳微信确认。绑定 openid 是前提。

---

## POST /transfer-auth — 开启免确认到账

申请免确认授权，返回拉起微信授权页的 `package_info`。

### 入参

无（`user_id` 从 JWT 取）。

### 出参

响应 `200`:`TransferAuthResultOut`

| 字段 | 类型 | 说明 |
|---|---|---|
| `already_active` | bool | 是否已是开启状态（无需再授权） |
| `package_info` | string \| null | 拉起微信授权页的 package；已开启时为空 |
| `mch_id` | string \| null | 商户号 |
| `app_id` | string \| null | 微信 AppID |

Mock 出参（首次申请）:
```json
{
  "already_active": false,
  "package_info": "affirmTransferAuth|{\"mchId\":\"1234567890\",\"appId\":\"wxabc123\",\"package\":\"affirm_biz_123\"}",
  "mch_id": "1234567890",
  "app_id": "wxabc123"
}
```

Mock 出参（已开启，无需重复授权）:
```json
{
  "already_active": true,
  "package_info": null,
  "mch_id": "1234567890",
  "app_id": "wxabc123"
}
```

### 错误码
- `400` 未绑定微信
- `502` 微信授权接口调用失败
- `503` 微信支付授权未配置

---

## GET /transfer-auth/status — 查免确认授权状态

从微信授权页返回后轮询。

### 入参

无（`user_id` 从 JWT 取）。

### 出参

响应 `200`:`TransferAuthStatusOut`

| 字段 | 类型 | 说明 |
|---|---|---|
| `state` | string | `none`（未开启）/ `pending`（待确认）/ `active`（已开启）/ `closed`（已关闭） |
| `enabled` | bool | 是否已开启免确认到账 |

Mock 出参:
```json
{
  "state": "active",
  "enabled": true
}
```

---

## POST /transfer-auth/close — 关闭免确认到账

解除授权，恢复每次提现跳微信确认。

### 入参

无（`user_id` 从 JWT 取）。

### 出参

响应 `200`:`TransferAuthStatusOut`（同上）

Mock 出参:
```json
{
  "state": "closed",
  "enabled": false
}
```

---

## 错误码（通用）
- `401` 未鉴权 / token 失效
- `503` 微信支付授权未配置