itom-group/chat-deploy

Fork 0

Files

kim.dev.6789 b7f8db7d08 复制项目

2026-01-14 22:35:45 +08:00

10 KiB

Raw Blame History

钱包相关接口汇总

基础信息

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

接口列表

1. 获取钱包余额

接口地址: POST /wallet/balance

请求参数: 无

响应参数:

{
  "errCode": 0,
  "data": {
    "balance": 10000  // 余额（单位：分）
  }
}

2. 获取钱包详细信息

接口地址: POST /wallet/info

请求参数: 无

响应参数:

{
  "errCode": 0,
  "data": {
    "balance": 10000,                    // 余额（单位：分）
    "withdrawAccount": "string",         // 提现账号
    "withdrawAccountType": 1,            // 提现账号类型：1-支付宝，2-微信，3-银行卡
    "withdrawReceiveAccount": "string",  // 提现收款账号
    "hasPaymentPassword": true,          // 是否已设置支付密码
    "realNameAuth": {                    // 实名认证信息（可选）
      "idCard": "string",
      "idCardPhotoFront": "string",
      "idCardPhotoBack": "string",
      "name": "string"
    }
  }
}

3. 获取余额明细

接口地址: POST /wallet/balance_records

请求参数:

字段名	类型	必填	说明
pagination	object	是	分页参数
pagination.pageNumber	int32	是	页码（从1开始）
pagination.showNumber	int32	是	每页显示数量
type	int32	否	变动类型（可选，0表示查询所有类型）：1-充值，2-提现/提款，3-消费，4-退款，5-奖励，6-后台充值，7-发红包，8-抢红包，99-其他

响应参数:

{
  "errCode": 0,
  "data": {
    "total": 100,
    "records": [
      {
        "id": "string",
        "userID": "string",
        "amount": 10000,
        "type": 1,
        "beforeBalance": 0,
        "afterBalance": 10000,
        "orderID": "string",
        "transactionID": "string",
        "redPacketID": "string",
        "remark": "string",
        "createTime": 1234567890123
      }
    ]
  }
}

变动类型说明:

类型值	类型名称	说明
1	充值	用户充值
2	提现/提款	提现申请
3	消费	消费支出
4	退款	退款收入
5	奖励	奖励收入
6	后台充值	管理员后台充值
7	发红包	发红包（减少余额）
8	抢红包	抢红包（增加余额）
99	其他	其他类型

业务逻辑:

从 token 中获取当前用户ID
如果指定了 type，按类型查询；否则查询所有类型
按创建时间倒序排列
支持分页查询

请求示例:

查询所有记录：

{
  "pagination": {
    "pageNumber": 1,
    "showNumber": 10
  }
}

按类型查询（只查询充值记录）：

{
  "pagination": {
    "pageNumber": 1,
    "showNumber": 10
  },
  "type": 1
}

4. 设置支付密码

接口地址: POST /wallet/payment_password/set

请求参数:

字段名	类型	必填	说明
newPassword	string	是	新支付密码
oldPassword	string	条件必填	旧支付密码（修改时必填，首次设置时不需要）

响应参数:

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

业务逻辑:

首次设置支付密码:
- 钱包不存在或未设置支付密码
- 不需要提供 oldPassword
- 如果提供了 oldPassword，会返回错误
- 如果钱包不存在，会自动创建钱包并设置支付密码
修改支付密码:
- 已设置支付密码
- 必须提供 oldPassword
- 验证旧密码是否正确
- 验证新密码不能与旧密码相同

错误码说明:

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

请求示例:

首次设置：

{
  "newPassword": "123456"
}

修改密码：

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

4. 设置提现账号

接口地址: POST /wallet/withdraw_account/set

请求参数:

字段名	类型	必填	说明
account	string	是	提现账号
accountType	int32	是	账号类型：1-支付宝，2-微信，3-银行卡

响应参数:

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

账号类型说明:

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

错误码说明:

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

请求示例:

设置支付宝账号：

{
  "account": "13800138000",
  "accountType": 1
}

设置银行卡：

{
  "account": "6222021234567890123",
  "accountType": 3
}

5. 申请提现

接口地址: POST /wallet/withdraw/apply

请求参数:

字段名	类型	必填	说明
amount	int64	是	提现金额（单位：分，必须 > 0）
paymentPassword	string	是	支付密码
ip	string	否	申请IP
deviceID	string	否	设备ID
platform	string	否	平台（iOS、Android、Web等）
deviceModel	string	否	设备型号
deviceBrand	string	否	设备品牌
osVersion	string	否	操作系统版本
appVersion	string	否	应用版本

注意:

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

响应参数:

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

错误码说明:

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

6. 获取提现申请列表

接口地址: POST /wallet/withdraw/list

请求参数:

字段名	类型	必填	说明
pagination	object	是	分页参数
pagination.pageNumber	int32	是	页码（从1开始）
pagination.showNumber	int32	是	每页显示数量

响应参数:

{
  "errCode": 0,
  "data": {
    "total": 100,
    "applications": [
      {
        "id": "string",
        "userID": "string",
        "amount": 10000,
        "withdrawAccount": "string",
        "withdrawAccountType": 1,
        "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	待审核	用户已提交，等待管理员审核
2	已通过	管理员审核通过
3	已拒绝	管理员审核拒绝
4	处理中	审核通过后，正在处理提现
5	已完成	提现已完成

RPC 接口对应关系

HTTP 接口	RPC 方法	请求消息	响应消息
`/wallet/balance`	`GetWalletBalance`	`GetWalletBalanceReq`	`GetWalletBalanceResp`
`/wallet/info`	`GetWalletInfo`	`GetWalletInfoReq`	`GetWalletInfoResp`
`/wallet/balance_records`	`GetWalletBalanceRecords`	`GetWalletBalanceRecordsReq`	`GetWalletBalanceRecordsResp`
`/wallet/payment_password/set`	`SetPaymentPassword`	`SetPaymentPasswordReq`	`SetPaymentPasswordResp`
`/wallet/withdraw_account/set`	`SetWithdrawAccount`	`SetWithdrawAccountReq`	`SetWithdrawAccountResp`
`/wallet/withdraw/apply`	`CreateWithdrawApplication`	`CreateWithdrawApplicationReq`	`CreateWithdrawApplicationResp`
`/wallet/withdraw/list`	`GetWithdrawApplications`	`GetWithdrawApplicationsReq`	`GetWithdrawApplicationsResp`

使用流程示例

1. 首次使用钱包

# 1. 获取钱包信息（检查是否已设置支付密码）
POST /wallet/info

# 2. 如果 hasPaymentPassword 为 false，设置支付密码
POST /wallet/payment_password/set
{
  "newPassword": "123456"
}

# 3. 设置提现账号
POST /wallet/withdraw_account/set
{
  "account": "13800138000",
  "accountType": 1  // 1-支付宝，2-微信，3-银行卡
}

# 4. 申请提现（提现账号从钱包中自动获取）
POST /wallet/withdraw/apply
{
  "amount": 10000,
  "paymentPassword": "123456"
}

2. 修改支付密码

# 修改支付密码
POST /wallet/payment_password/set
{
  "newPassword": "654321",
  "oldPassword": "123456"
}

3. 查看提现记录

# 获取提现申请列表
POST /wallet/withdraw/list
{
  "pagination": {
    "pageNumber": 1,
    "showNumber": 10
  }
}

注意事项

支付密码设置:
- 首次设置不需要旧密码
- 修改时必须提供正确的旧密码
- 新密码不能与旧密码相同
提现申请:
- 必须已设置支付密码
- 必须验证支付密码
- 余额必须足够
- 需要设置提现账号
权限控制:
- 所有接口都需要 token 认证
- 用户只能操作自己的钱包
- 用户只能查看自己的提现申请列表
数据单位:
- 所有金额单位均为"分"（1元 = 100分）
- 时间戳单位为毫秒

10 KiB Raw Blame History Unescape Escape

钱包相关接口汇总

基础信息

接口列表

1. 获取钱包余额

2. 获取钱包详细信息

3. 获取余额明细

4. 设置支付密码

4. 设置提现账号

5. 申请提现

6. 获取提现申请列表

RPC 接口对应关系

使用流程示例

1. 首次使用钱包

2. 修改支付密码

3. 查看提现记录

注意事项

10 KiB

Raw Blame History