# 暴涨支付接入方案：微信支付与支付宝

更新时间：2026-07-23

## 目标

第一阶段先支持浏览器端会员/积分充值闭环：

- 微信支付：优先接入 Native 扫码支付，服务端下单后前端展示二维码。
- 支付宝：优先接入电脑网站支付，服务端生成跳转表单或支付链接。
- 支付结果只以服务端异步通知为准，前端回跳和轮询只用于展示。
- 复用现有会员、积分、订单后台，不改变当前 USDT 支付的人工确认能力。

第二阶段再扩展：

- 微信小程序端：接入微信 JSAPI/小程序支付。
- H5 移动浏览器：接入支付宝手机网站支付、微信 H5/JSAPI 视使用场景确定。
- 退款、对账、发票、风控限额、分账等运营能力。

## 需要准备的商户材料

微信支付：

- 微信支付商户号 `MCH_ID`
- API v3 密钥 `WECHAT_PAY_API_V3_KEY`
- 商户 API 证书序列号 `WECHAT_PAY_SERIAL_NO`
- 商户私钥 PEM 文件
- AppID：Web Native 可用公众号/小程序/App 的关联 AppID；小程序支付需要小程序 AppID
- 支付结果通知域名：必须是公网 HTTPS，如 `https://crazyee.com/api/payments/wechat/notify`

支付宝：

- 支付宝开放平台应用 `APP_ID`
- 应用私钥
- 支付宝公钥或应用公钥证书模式材料
- 签名方式建议 `RSA2`
- 支付结果通知域名：如 `https://crazyee.com/api/payments/alipay/notify`
- 前台回跳地址：如 `https://crazyee.com/#/billing/result`

通用：

- 已备案且可 HTTPS 访问的域名
- 生产环境密钥保存位置：只放服务器环境变量或 Docker secret，不进 Git
- 退款/客服/对账负责人

## 建议数据模型

新增或改造统一订单表 `qd_payment_orders`：

- `id`
- `user_id`
- `provider`: `wechat` / `alipay` / `usdt`
- `channel`: `wechat_native` / `wechat_jsapi` / `alipay_page` / `alipay_wap`
- `out_trade_no`: 本系统唯一订单号
- `provider_trade_no`: 微信/支付宝交易号
- `plan_code`: `monthly` / `yearly` / `lifetime` / `credits_pack`
- `amount_cny`: 人民币金额，单位元，Decimal
- `currency`: 默认 `CNY`
- `status`: `pending` / `paid` / `closed` / `expired` / `refunded` / `failed`
- `prepay_payload`: 微信 `code_url` 或支付宝跳转表单摘要
- `notify_payload`: 验签后的通知内容 JSON
- `paid_at`
- `expires_at`
- `created_at`
- `updated_at`

新增流水表 `qd_payment_events`：

- `order_id`
- `provider`
- `event_type`: `created` / `notify_received` / `query_paid` / `granted` / `refund`
- `request_id`
- `payload`
- `created_at`

原则：

- 订单支付成功和会员/积分发放必须在一个幂等事务里完成。
- `out_trade_no` 必须唯一，通知重复到达时不能重复发放。
- 前端看到“支付成功”后仍要以服务端订单状态为准。

## 后端接口设计

用户侧：

- `GET /api/payments/plans`
  - 返回可购买套餐、价格、赠送积分、支付开关。
- `POST /api/payments/orders`
  - 入参：`provider`、`channel`、`plan_code`
  - 出参：
    - 微信 Native：`order_id`、`out_trade_no`、`code_url`、`expires_at`
    - 支付宝 Page：`order_id`、`payment_form` 或 `payment_url`
- `GET /api/payments/orders/{id}`
  - 前端轮询订单状态。
- `POST /api/payments/orders/{id}/close`
  - 用户取消未支付订单。

通知侧：

- `POST /api/payments/wechat/notify`
  - 验证微信支付签名，使用 API v3 密钥解密通知资源。
  - 确认为支付成功后，更新订单并发放会员/积分。
  - 按微信要求返回成功接收响应。
- `POST /api/payments/alipay/notify`
  - 使用支付宝公钥验签。
  - 检查 `app_id`、`out_trade_no`、金额、收款方。
  - `trade_status` 为支付成功/交易完成后发放权益。
  - 按支付宝要求返回 `success`。

管理侧：

- `GET /api/users/admin-payment-orders`
- `POST /api/users/admin-payment-orders/{id}/refresh`
- `POST /api/users/admin-payment-orders/{id}/manual-confirm`
- `POST /api/users/admin-payment-orders/{id}/refund`

## 前端改造

充值页：

- 支付方式选择：微信支付、支付宝、USDT。
- 微信 Native：显示二维码、金额、倒计时、复制订单号、轮询状态。
- 支付宝 Page：点击后新窗口/当前页跳转到支付宝收银台，回跳页只显示“正在确认支付结果”。
- 管理后台订单列表增加人民币订单筛选。

小程序端后续：

- 登录态绑定微信 `openid`。
- 下单接口传 `channel=wechat_jsapi`。
- 后端返回 `timeStamp`、`nonceStr`、`package`、`signType`、`paySign`。
- 小程序调用 `wx.requestPayment`，支付结果仍等后端通知确认。

## 安全与风控

- 私钥、API v3 密钥、支付宝私钥禁止写入仓库。
- 通知接口必须验签，且不能只相信前端回跳。
- 金额、币种、商户号、AppID 必须二次校验。
- 权益发放幂等：同一订单只能发放一次。
- 保留原始通知 payload 和验签结果，便于对账。
- 单用户短时间下单频率限制，避免恶意刷单。
- 订单超时自动关闭，微信 Native 的二维码有效期按官方说明处理。

## 实施阶段

第一阶段：Web 支付基础闭环

- 增加统一支付配置与订单表。
- 接微信 Native、支付宝电脑网站支付。
- 支持会员套餐购买、积分发放、订单轮询。
- 后台可查订单，可人工补单。

第二阶段：生产硬化

- 支付结果主动查询补偿任务。
- 日账单下载与本地订单对账。
- 告警：通知验签失败、金额不一致、发放失败。
- 灰度开关：按 provider/channel 开启或关闭。

第三阶段：小程序支付

- 完成微信小程序登录与 `openid` 绑定。
- 接入微信 JSAPI/小程序支付。
- 小程序端支付结果页和会员状态刷新。

第四阶段：退款与运营

- 退款接口与后台操作流。
- 套餐折扣码、发票字段、财务导出。
- 风险用户限制与黑名单。

## 官方参考

- 微信支付 Native 支付文档：https://pay.wechatpay.cn/doc/v3/partner/4012091224
- 支付宝电脑网站支付接口：https://opendocs.alipay.com/open/028r8t
- 支付宝异步通知说明：https://opendocs.alipay.com/support/01rfuz
- 支付宝手机网站支付文档：https://docs.open.alipay.com/60/104790/