yml/hfb_sys
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
87673288ef611e1d183aa44e9d62133050660779
hfb_sys/docs/提现功能API文档.md
T
yml 8a2d2f2a18 后端提现增加
2026-06-06 10:08:39 +08:00

12 KiB
Raw Blame History

提现功能 API 文档

目录

收款账号管理 API

1. 查询收款账号列表

请求

GET /api/payment-accounts?page=1&page_size=20
Authorization: Bearer {user_token}

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "user_id": 123,
        "account_type": "alipay",
        "account_name": "张三",
        "account_no": "138****5678",
        "bank_name": "",
        "bank_branch": "",
        "certificate_urls": ["https://..."],
        "is_default": true,
        "status": "active",
        "created_at": "2026-06-06T10:00:00Z",
        "updated_at": "2026-06-06T10:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

2. 查询收款账号详情

请求

GET /api/payment-accounts/:id
Authorization: Bearer {user_token}

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "user_id": 123,
    "account_type": "alipay",
    "account_name": "张三",
    "account_no": "138****5678",
    "bank_name": "",
    "bank_branch": "",
    "certificate_urls": ["https://..."],
    "is_default": true,
    "status": "active",
    "created_at": "2026-06-06T10:00:00Z",
    "updated_at": "2026-06-06T10:00:00Z"
  }
}

3. 添加收款账号

请求

POST /api/payment-accounts
Authorization: Bearer {user_token}
Content-Type: application/json

{
  "account_type": "alipay",      // alipay | wechat | bank
  "account_name": "张三",          // 必须与实名认证姓名一致
  "account_no": "13812345678",    // 支付宝账号/微信号/银行卡号
  "bank_name": "中国工商银行",     // 银行卡必填
  "bank_branch": "北京分行",       // 银行卡可选
  "certificate_urls": [           // 凭证截图（可选）
    "https://..."
  ]
}

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "user_id": 123,
    "account_type": "alipay",
    "account_name": "张三",
    "account_no": "138****5678",
    "is_default": false,
    "status": "active",
    "created_at": "2026-06-06T10:00:00Z",
    "updated_at": "2026-06-06T10:00:00Z"
  }
}

错误响应

{
  "code": 40001,
  "message": "账户名必须与实名认证姓名一致"
}

{
  "code": 40002,
  "message": "请先完成实名认证"
}

{
  "code": 40003,
  "message": "收款账号数量已达上限（最多5个）"
}

4. 更新收款账号

请求

PUT /api/payment-accounts/:id
Authorization: Bearer {user_token}
Content-Type: application/json

{
  "bank_branch": "北京朝阳支行",
  "certificate_urls": ["https://..."]
}

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "account_type": "bank",
    "account_name": "张三",
    "account_no": "6222****1234",
    "bank_name": "中国工商银行",
    "bank_branch": "北京朝阳支行",
    "is_default": false,
    "status": "active",
    "created_at": "2026-06-06T10:00:00Z",
    "updated_at": "2026-06-06T10:05:00Z"
  }
}

5. 删除收款账号

请求

DELETE /api/payment-accounts/:id
Authorization: Bearer {user_token}

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "deleted": true
  }
}

6. 设置默认收款账号

请求

POST /api/payment-accounts/:id/set-default
Authorization: Bearer {user_token}

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "updated": true
  }
}

提现申请 API (用户端)

1. 创建提现申请

请求

POST /api/withdrawals
Authorization: Bearer {user_token}
Content-Type: application/json

{
  "payment_account_id": 1,
  "amount": 100.00
}

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "withdraw_no": "WD17362512001a2b3c4d",
    "user_id": 123,
    "amount": 100.00,
    "fee": 0.00,
    "actual_amount": 100.00,
    "account_type": "alipay",
    "account_name": "张三",
    "account_no": "138****5678",
    "bank_name": "",
    "status": "pending",
    "review_remark": "",
    "created_at": "2026-06-06T10:00:00Z",
    "updated_at": "2026-06-06T10:00:00Z",
    "reviewed_at": null,
    "paid_at": null
  }
}

错误响应

{
  "code": 40001,
  "message": "提现金额低于最小限额"
}

{
  "code": 40002,
  "message": "提现金额超过最大限额"
}

{
  "code": 40003,
  "message": "余额不足"
}

2. 查询提现列表

请求

GET /api/withdrawals?page=1&page_size=20
Authorization: Bearer {user_token}

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "withdraw_no": "WD17362512001a2b3c4d",
        "user_id": 123,
        "amount": 100.00,
        "fee": 0.00,
        "actual_amount": 100.00,
        "account_type": "alipay",
        "account_name": "张三",
        "account_no": "138****5678",
        "bank_name": "",
        "status": "completed",
        "review_remark": "审核通过",
        "created_at": "2026-06-06T10:00:00Z",
        "updated_at": "2026-06-06T10:30:00Z",
        "reviewed_at": "2026-06-06T10:10:00Z",
        "paid_at": "2026-06-06T10:30:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

3. 查询提现详情

请求

GET /api/withdrawals/:id
Authorization: Bearer {user_token}

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "withdraw_no": "WD17362512001a2b3c4d",
    "user_id": 123,
    "amount": 100.00,
    "fee": 0.00,
    "actual_amount": 100.00,
    "account_type": "alipay",
    "account_name": "张三",
    "account_no": "138****5678",
    "bank_name": "",
    "status": "processing",
    "review_remark": "审核通过",
    "created_at": "2026-06-06T10:00:00Z",
    "updated_at": "2026-06-06T10:10:00Z",
    "reviewed_at": "2026-06-06T10:10:00Z",
    "paid_at": null
  }
}

4. 取消提现申请

请求

POST /api/withdrawals/:id/cancel
Authorization: Bearer {user_token}

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "cancelled": true
  }
}

错误响应

{
  "code": 40001,
  "message": "提现申请状态已锁定，无法操作"
}

提现管理 API (管理员端)

1. 查询提现列表

请求

GET /api/admin/withdrawals?status=pending&page=1&page_size=20
Authorization: Bearer {admin_token}
X-Required-Permission: withdrawal:list

查询参数

  • status: 状态筛选 (pending | processing | completed | rejected | cancelled)
  • user_id: 用户ID筛选
  • page: 页码
  • page_size: 每页数量

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "withdraw_no": "WD17362512001a2b3c4d",
        "user_id": 123,
        "user_nickname": "用户昵称",
        "user_phone": "138****5678",
        "amount": 100.00,
        "fee": 0.00,
        "actual_amount": 100.00,
        "payment_account_id": 1,
        "account_type": "alipay",
        "account_name": "张三",
        "account_no": "13812345678",  // 管理员可见完整账号
        "bank_name": "",
        "bank_branch": "",
        "status": "pending",
        "reviewed_by": null,
        "reviewed_by_name": "",
        "reviewed_at": null,
        "review_remark": "",
        "paid_by": null,
        "paid_by_name": "",
        "paid_at": null,
        "payment_proof_url": "",
        "payment_remark": "",
        "created_at": "2026-06-06T10:00:00Z",
        "updated_at": "2026-06-06T10:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

2. 查询提现详情

请求

GET /api/admin/withdrawals/:id
Authorization: Bearer {admin_token}
X-Required-Permission: withdrawal:detail

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "withdraw_no": "WD17362512001a2b3c4d",
    "user_id": 123,
    "user_nickname": "用户昵称",
    "user_phone": "13812345678",
    "amount": 100.00,
    "fee": 0.00,
    "actual_amount": 100.00,
    "payment_account_id": 1,
    "account_type": "alipay",
    "account_name": "张三",
    "account_no": "13812345678",
    "bank_name": "",
    "bank_branch": "",
    "status": "pending",
    "reviewed_by": null,
    "reviewed_by_name": "",
    "reviewed_at": null,
    "review_remark": "",
    "paid_by": null,
    "paid_by_name": "",
    "paid_at": null,
    "payment_proof_url": "",
    "payment_remark": "",
    "created_at": "2026-06-06T10:00:00Z",
    "updated_at": "2026-06-06T10:00:00Z"
  }
}

3. 审核提现申请

请求

POST /api/admin/withdrawals/:id/review
Authorization: Bearer {admin_token}
X-Required-Permission: withdrawal:review
Content-Type: application/json

{
  "approved": true,
  "remark": "审核通过"
}

审核通过响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "withdraw_no": "WD17362512001a2b3c4d",
    "status": "processing",
    "reviewed_by": 10,
    "reviewed_by_name": "财务管理员",
    "reviewed_at": "2026-06-06T10:10:00Z",
    "review_remark": "审核通过",
    ...
  }
}

审核拒绝请求

{
  "approved": false,
  "remark": "账号信息不符"
}

审核拒绝响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "withdraw_no": "WD17362512001a2b3c4d",
    "status": "rejected",
    "reviewed_by": 10,
    "reviewed_by_name": "财务管理员",
    "reviewed_at": "2026-06-06T10:10:00Z",
    "review_remark": "账号信息不符",
    ...
  }
}

4. 确认打款

请求

POST /api/admin/withdrawals/:id/confirm-payment
Authorization: Bearer {admin_token}
X-Required-Permission: withdrawal:pay
Content-Type: application/json

{
  "payment_proof_url": "https://storage.example.com/proofs/proof_123.jpg",
  "remark": "已通过支付宝转账"
}

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "withdraw_no": "WD17362512001a2b3c4d",
    "status": "completed",
    "paid_by": 10,
    "paid_by_name": "财务管理员",
    "paid_at": "2026-06-06T10:30:00Z",
    "payment_proof_url": "https://storage.example.com/proofs/proof_123.jpg",
    "payment_remark": "已通过支付宝转账",
    ...
  }
}

状态说明

提现状态 (status)

状态 说明 允许操作
pending 待审核 用户可取消、管理员可审核
processing 处理中 管理员可确认打款
completed 已完成 无
rejected 已拒绝 无
cancelled 已取消 无

账号类型 (account_type)

类型 说明
alipay 支付宝
wechat 微信
bank 银行卡

错误码说明

错误码 说明
40001 请求参数错误
40002 实名认证未通过
40003 账号数量限制
40004 提现金额错误
40005 余额不足
40006 状态锁定
40401 未找到资源
40301 未授权
50001 服务器错误

接口权限说明

用户端接口

所有用户端接口需要携带用户 Token (Authorization: Bearer {user_token})

管理员端接口

所有管理员端接口需要：

  1. 携带管理员 Token (Authorization: Bearer {admin_token})
  2. 拥有对应的权限

提现管理权限列表

  • withdrawal:list - 查看提现申请列表
  • withdrawal:detail - 查看提现详情
  • withdrawal:review - 审核提现申请
  • withdrawal:pay - 确认打款

财务角色 (finance) 默认拥有以上所有权限。

Reference in New Issue View Git Blame Copy Permalink