guke
a563c1ca4b
docs/api目录文档分类和补全 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #111
109 lines
2.3 KiB
Markdown
109 lines
2.3 KiB
Markdown
# 免确认收款授权（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` 微信支付授权未配置
|