支付接入方案

一期推荐路线

11API 一期建议采用：

1. 支付页独立
2. 支付成功生成兑换码
3. 用户回到主站控制台兑换
4. New API 继续负责额度与令牌

不要一开始就把支付和 New API 强耦合在一起。

推荐链路

pay.11api.top 下单
-> 支付完成
-> 生成兑换码
-> 用户在 11api.top/console/redemption 兑换
-> 用户在 11api.top/console/token 创建 key

为什么推荐兑换码

1. 支付系统故障不会影响 API 服务
2. 对账更简单
3. 退款更容易处理
4. 活动码、渠道码、赠送码都能统一管理

数据模型建议

至少要有这些业务表：

1. orders
2. payment_webhooks
3. redeem_batches
4. redeem_codes
5. wallet_ledger
6. refund_requests

一期状态设计

订单状态

1. pending
2. paid
3. fulfilled
4. refunded
5. closed

这里的 paid 表示已经确认收款但还没有完成履约。授权额度订单只有在 New API 原生兑换码同步成功后才进入 fulfilled；同步失败保留 paid + fulfillment_status=sync_failed，后台重试，不发本地假码。

兑换码状态

1. unused
2. used
3. frozen
4. expired

接入方式建议

方案 A：独立支付页 + webhook

推荐指数最高。

支付服务负责：

1. 创建订单
2. 接收回调
3. 发放兑换码
4. 发邮件

主站负责：

1. 展示兑换入口
2. 兑换额度
3. 创建 token

方案 B：卡密系统

更快上线，适合先小规模卖。

方案 C：自动充值到账

适合二期再做，复杂度高于兑换码模式。

上线顺序

1. 先让 pay.11api.top 能出订单
2. 再让后台能生成兑换码
3. 最后再做自动邮件和发票流程

当前项目已经落地的骨架

仓库内置了 pay-service，已经接入 docker-compose 与 pay.11api.top。

当前可直接使用：

1. 套餐展示页
2. 创建订单接口
3. 订单状态查询
4. epay 收银台跳转
5. epay 异步回调验签
6. mock 支付成功回调
7. 自动调用 New API 原生兑换码接口发码
8. 后台人工标记到账

已有接口

1. 健康检查

curl https://pay.11api.top/api/health

2. 创建订单

curl --request POST \
  --url https://pay.11api.top/api/orders \
  --header 'Content-Type: application/json' \
  --data '{
    "planId": "growth",
    "email": "user@example.com",
    "contact": "telegram:@demo"
  }'

3. 模拟支付成功

在服务器执行：

cd /opt/11api/deploy
./scripts/mock-pay-order.sh <order_no>

4. 查询订单和兑换码

curl "https://pay.11api.top/api/orders/<order_no>?lookupToken=<lookup_token>"

lookupToken 会在创建订单成功时返回一次，后端只保存哈希。不要只靠订单号公开查询订单；订单详情可能包含邮箱、付款状态、人工收款指引和兑换码同步状态。

真实支付模式

试营业早期如果使用 manual，支付页会在创建订单后展示一份可复制付款信息：金额、订单号、转账备注、联系方式、处理步骤和可选二维码。上线前用下面命令验证：

cd /opt/11api/deploy
./scripts/smoke-manual-checkout.sh

如果要直接商用，建议把 .env 设置为：

PAY_PROVIDER=epay
PAY_DEFAULT_METHOD=alipay
EPAY_GATEWAY_URL=https://你的易支付网关
EPAY_PID=你的商户号
EPAY_KEY=你的商户密钥
EPAY_SITENAME=11API

支付完成后，epay 会回调：

https://pay.11api.top/api/webhooks/epay/notify

支付返回页会落到：

https://pay.11api.top/return

正式接支付时怎么替换

后面只需要把正式支付平台的回调，替换到当前 mock webhook 的同类处理逻辑：

1. 验签
2. 幂等处理
3. 标记订单已支付
4. 发放兑换码
5. 通知用户回主站兑换

也就是说，一期现在已经把“订单 -> 回调 -> 兑换码”这条主链搭起来了，后续只是替换支付渠道，不需要重做整套业务结构。