chat-deploy/docs/API_WITHDRAW_APPLICATION.md

提现申请接口文档

基础信息

• 基础路径: /wallet
• 认证方式: 所有接口都需要在请求头中携带 token（通过 mw.CheckToken 中间件验证）
• 请求方法: 所有接口均为 POST
• Content-Type: application/json

响应格式说明

所有接口的响应格式统一为：

{
  "errCode": 0,        // 错误码，0 表示成功
  "errMsg": "",        // 错误消息
  "errDlt": "",        // 错误详情
  "data": {}           // 响应数据
}

公共数据结构

RequestPagination（分页信息）

{
  "pageNumber": 1,    // 页码（从1开始）
  "showNumber": 10    // 每页显示数量
}

WithdrawApplicationInfo（提现申请信息）

{
  "id": "string",                // 申请ID
  "userID": "string",            // 用户ID
  "amount": 10000,               // 提现金额（单位：分）
  "withdrawAccount": "string",   // 提现账号
  "withdrawAccountType": 1,      // 提现账号类型：1-支付宝，2-微信，3-银行卡
  "status": 1,                   // 申请状态：1-待审核，2-已通过，3-已拒绝，4-处理中，5-已完成
  "auditorID": "string",         // 审核人ID（管理员ID）
  "auditTime": 1234567890123,    // 审核时间（毫秒时间戳，未审核时为0）
  "auditRemark": "string",       // 审核备注
  "ip": "string",                // 申请IP
  "deviceID": "string",          // 设备ID
  "platform": "string",          // 平台（iOS、Android、Web等）
  "deviceModel": "string",       // 设备型号
  "deviceBrand": "string",       // 设备品牌
  "osVersion": "string",         // 操作系统版本
  "appVersion": "string",        // 应用版本
  "remark": "string",            // 申请备注
  "createTime": 1234567890123,   // 创建时间（毫秒时间戳）
  "updateTime": 1234567890123    // 更新时间（毫秒时间戳）
}

提现申请状态说明

状态值	状态名称	说明
1	待审核	用户已提交申请，等待管理员审核
2	已通过	管理员审核通过
3	已拒绝	管理员审核拒绝
4	处理中	审核通过后，正在处理提现
5	已完成	提现已完成

---

接口列表

1. 设置支付密码

接口地址: /wallet/payment_password/set

请求参数:

{
  "newPassword": "string",  // 新支付密码（必填）
  "oldPassword": "string"   // 旧支付密码（修改时必填，首次设置时不需要）
}

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}

业务逻辑:

1. 首次设置支付密码（钱包不存在或未设置支付密码）:

   • 不需要提供 oldPassword
   • 如果提供了 oldPassword，会返回错误
   • 如果钱包不存在，会自动创建钱包并设置支付密码

2. 修改支付密码（已设置支付密码）:

   • 必须提供 oldPassword
   • 验证旧密码是否正确
   • 验证新密码不能与旧密码相同
   • 更新支付密码

错误码说明:

错误码	错误信息	说明
400	新支付密码不能为空	newPassword 为空
400	修改支付密码需要提供旧密码	已设置密码但未提供 oldPassword
400	首次设置支付密码不需要提供旧密码	未设置密码但提供了 oldPassword
400	旧支付密码错误	oldPassword 验证失败
400	新密码不能与旧密码相同	newPassword == oldPassword

请求示例:

首次设置：

{
  "newPassword": "123456"
}

修改密码：

{
  "newPassword": "654321",
  "oldPassword": "123456"
}

---

2. 设置提现账号

接口地址: /wallet/withdraw_account/set

请求参数:

{
  "account": "string",      // 提现账号（必填）
  "accountType": 1          // 账号类型（必填）：1-支付宝，2-微信，3-银行卡
}

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}

账号类型说明:

类型值	类型名称	说明
1	支付宝	支付宝账号
2	微信	微信账号
3	银行卡	银行卡号

错误码说明:

错误码	错误信息	说明
400	提现账号不能为空	account 为空
400	账号类型无效，必须是1-支付宝，2-微信，3-银行卡	accountType 不在有效范围内

业务逻辑:

1. 验证必填字段（账号、账号类型）
2. 验证账号类型是否有效（1-3）
3. 更新钱包中的提现账号和账号类型

---

3. 申请提现

接口地址: /wallet/withdraw/apply

请求参数:

{
  "amount": 10000,              // 提现金额（单位：分，必填，必须大于0）
  "paymentPassword": "string",  // 支付密码（必填）
  "ip": "string",               // 申请IP（可选）
  "deviceID": "string",         // 设备ID（可选）
  "platform": "string",         // 平台（可选，如：iOS、Android、Web）
  "deviceModel": "string",     // 设备型号（可选，如：iPhone 14 Pro）
  "deviceBrand": "string",      // 设备品牌（可选，如：Apple）
  "osVersion": "string",        // 操作系统版本（可选，如：iOS 17.0）
  "appVersion": "string"        // 应用版本（可选）
}

注意:

• 提现账号从用户钱包中自动获取，不需要在请求中提供
• 如果钱包中未设置提现账号，会返回错误提示
• 备注（remark）由后台管理员在审核时填写，用户申请时不需要提供

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "applicationID": "uuid-string"  // 申请ID
  }
}

错误码说明:

错误码	错误信息	说明
400	提现金额必须大于0	amount <= 0
400	支付密码不能为空	paymentPassword 为空
400	钱包不存在，无法申请提现	用户钱包不存在
400	请先设置支付密码	用户未设置支付密码
400	支付密码错误	支付密码验证失败
400	余额不足，无法申请提现	钱包余额 < 提现金额
400	请先在钱包中设置提现账号	钱包中未设置提现账号

业务逻辑:

1. 验证必填字段（金额、支付密码）
2. 获取用户钱包信息
3. 验证支付密码
4. 检查余额是否足够
5. 检查钱包中是否设置了提现账号（从钱包中获取）
6. 创建提现申请记录（状态：待审核，提现账号从钱包中获取）

---

4. 获取提现申请列表

接口地址: /wallet/withdraw/list

请求参数:

{
  "pagination": {
    "pageNumber": 1,   // 页码（从1开始）
    "showNumber": 10    // 每页显示数量
  }
}

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 100,                    // 总数
    "applications": [                // 申请列表
      {
        "id": "string",
        "userID": "string",
        "amount": 10000,
        "withdrawAccount": "string",
        "status": 1,
        "auditorID": "string",
        "auditTime": 1234567890123,
        "auditRemark": "string",
        "ip": "string",
        "deviceID": "string",
        "platform": "string",
        "deviceModel": "string",
        "deviceBrand": "string",
        "osVersion": "string",
        "appVersion": "string",
        "remark": "string",
        "createTime": 1234567890123,
        "updateTime": 1234567890123
      }
    ]
  }
}

业务逻辑:

1. 从 token 中获取当前用户ID
2. 根据用户ID查询提现申请列表
3. 按创建时间倒序排列
4. 支持分页查询

---

请求示例

申请提现

curl -X POST http://your-domain/wallet/withdraw/apply \
  -H "Content-Type: application/json" \
  -H "token: your-token" \
  -d '{
    "amount": 10000,
    "paymentPassword": "123456",
    "ip": "192.168.1.1",
    "deviceID": "device-uuid",
    "platform": "iOS",
    "deviceModel": "iPhone 14 Pro",
    "deviceBrand": "Apple",
    "osVersion": "iOS 17.0",
    "appVersion": "1.0.0"
  }'

响应示例:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "applicationID": "550e8400-e29b-41d4-a716-446655440000"
  }
}

获取提现申请列表

curl -X POST http://your-domain/wallet/withdraw/list \
  -H "Content-Type: application/json" \
  -H "token: your-token" \
  -d '{
    "pagination": {
      "pageNumber": 1,
      "showNumber": 10
    }
  }'

响应示例:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 5,
    "applications": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "userID": "user123",
        "amount": 10000,
        "withdrawAccount": "6222021234567890123",
        "status": 1,
        "auditorID": "",
        "auditTime": 0,
        "auditRemark": "",
        "ip": "192.168.1.1",
        "deviceID": "device-uuid",
        "platform": "iOS",
        "deviceModel": "iPhone 14 Pro",
        "deviceBrand": "Apple",
        "osVersion": "iOS 17.0",
        "appVersion": "1.0.0",
        "remark": "提现备注",
        "createTime": 1704067200000,
        "updateTime": 1704067200000
      }
    ]
  }
}

---

RPC 接口说明

gRPC 服务

服务名: openim.chat.Chat

1. CreateWithdrawApplication

RPC 方法: CreateWithdrawApplication

请求消息: CreateWithdrawApplicationReq

响应消息: CreateWithdrawApplicationResp

2. SetPaymentPassword

RPC 方法: SetPaymentPassword

请求消息: SetPaymentPasswordReq

响应消息: SetPaymentPasswordResp

3. GetWithdrawApplications

RPC 方法: GetWithdrawApplications

请求消息: GetWithdrawApplicationsReq

响应消息: GetWithdrawApplicationsResp

---

注意事项

1. 支付密码验证: 申请提现时必须提供正确的支付密码
2. 余额检查: 系统会检查钱包余额是否足够，余额不足时无法申请
3. 提现账号: 如果钱包中已设置提现账号，可以不传 withdrawAccount，系统会使用钱包中的账号
4. 申请状态: 新创建的申请状态为"待审核"（status=1），需要管理员审核
5. 分页查询: 列表接口支持分页，默认按创建时间倒序排列
6. 权限控制: 用户只能查看自己的提现申请列表

---

相关接口

• 钱包余额查询
• 钱包信息查询
• 设置支付密码