zhibo/android-app/后端接口TODO清单-支付集成.md

后端接口 TODO 清单 - 支付集成模块

支付SDK集成说明

文件: RoomDetailActivity.java

需要集成的支付方式

1. 微信支付
2. 支付宝支付
3. 其他支付方式（可选）

1. 创建支付订单

接口路径: POST /api/payment/create 请求参数:

{
  "userId": "string",
  "orderType": "recharge",
  "amount": "number",
  "coinAmount": "number",
  "paymentMethod": "wechat|alipay",
  "rechargeOptionId": "string"
}

返回数据:

{
  "code": 200,
  "data": {
    "orderId": "string",
    "orderNo": "string",
    "amount": "number",
    "paymentParams": {
      "appId": "string",
      "partnerId": "string",
      "prepayId": "string",
      "packageValue": "string",
      "nonceStr": "string",
      "timeStamp": "string",
      "sign": "string"
    }
  }
}

2. 查询支付状态

接口路径: GET /api/payment/status/{orderId} 请求参数: orderId (路径参数) 返回数据:

{
  "code": 200,
  "data": {
    "orderId": "string",
    "status": "pending|success|failed|cancelled",
    "paidAt": "number",
    "amount": "number"
  }
}

3. 支付回调通知

接口路径: POST /api/payment/callback/wechat 或 /api/payment/callback/alipay 说明:

• 此接口由支付平台调用，不是前端调用
• 用于接收支付成功的异步通知
• 支付成功后更新订单状态和用户金币余额

4. 获取支付历史

接口路径: GET /api/payment/history 请求参数:

• userId: 用户ID（从token中获取）
• page (可选): 页码
• pageSize (可选): 每页数量 返回数据:

{
  "code": 200,
  "data": [
    {
      "orderId": "string",
      "orderNo": "string",
      "amount": "number",
      "coinAmount": "number",
      "status": "string",
      "paymentMethod": "string",
      "createdAt": "number",
      "paidAt": "number"
    }
  ]
}

微信支付集成步骤

1. 添加依赖

implementation 'com.tencent.mm.opensdk:wechat-sdk-android:6.8.0'

2. 配置微信支付

• 在微信开放平台注册应用
• 获取 AppID 和 AppSecret
• 配置支付回调URL

3. 调用支付

// 1. 创建支付订单，获取支付参数
// 2. 调用微信支付SDK
IWXAPI api = WXAPIFactory.createWXAPI(context, APP_ID);
PayReq request = new PayReq();
request.appId = paymentParams.getAppId();
request.partnerId = paymentParams.getPartnerId();
request.prepayId = paymentParams.getPrepayId();
request.packageValue = paymentParams.getPackageValue();
request.nonceStr = paymentParams.getNonceStr();
request.timeStamp = paymentParams.getTimeStamp();
request.sign = paymentParams.getSign();
api.sendReq(request);

4. 处理支付结果

// 在 WXPayEntryActivity 中接收支付结果
@Override
public void onResp(BaseResp resp) {
    if (resp.getType() == ConstantsAPI.COMMAND_PAY_BY_WX) {
        if (resp.errCode == 0) {
            // 支付成功
            // 查询订单状态确认
        } else if (resp.errCode == -2) {
            // 用户取消
        } else {
            // 支付失败
        }
    }
}

支付宝支付集成步骤

1. 添加依赖

implementation 'com.alipay.sdk:alipaysdk-android:15.8.11'

2. 配置支付宝

• 在支付宝开放平台注册应用
• 获取 AppID 和私钥
• 配置支付回调URL

3. 调用支付

// 1. 创建支付订单，获取支付参数（orderInfo）
// 2. 调用支付宝SDK
PayTask alipay = new PayTask(activity);
Map<String, String> result = alipay.payV2(orderInfo, true);

4. 处理支付结果

// 解析支付结果
String resultStatus = result.get("resultStatus");
if (TextUtils.equals(resultStatus, "9000")) {
    // 支付成功
    // 查询订单状态确认
} else if (TextUtils.equals(resultStatus, "6001")) {
    // 用户取消
} else {
    // 支付失败
}

支付流程

充值流程

1. 用户选择充值金额
2. 选择支付方式（微信/支付宝）
3. 调用创建支付订单接口
4. 获取支付参数
5. 调用支付SDK发起支付
6. 用户完成支付
7. 接收支付结果回调
8. 查询订单状态确认支付成功
9. 更新用户金币余额
10. 显示充值成功提示

安全建议

1. 支付参数签名验证
2. 订单金额二次验证
3. 防止重复支付
4. 支付超时处理
5. 异常订单处理

错误处理

• 网络错误: 提示用户重试
• 支付取消: 关闭支付页面
• 支付失败: 显示失败原因，允许重试
• 订单查询失败: 提示联系客服