创建充值单后立即调用 /api/v1/order/create-transaction。

成功后自动跳转 public/usdtCheckout?tradeId=...。
收银台按交易号展示网络、金额、二维码、地址及支付状态。
失败时显示处理阶段,支持使用原单重试,避免重复创建。
This commit is contained in:
lu7213 committed 2026-10-29 03:46:59 -04:00
1 parent 76f9e62253
commit b6b9120b85
8 files changed
+203 -6

No files matched your search

+6
View File
@@ -47,6 +47,7 @@ RENT_PAYMENT_MAINNET_MAX_AMOUNT=10000.00
1. 登录用户创建充值,服务端校验账户归属、ACTIVE 状态、网络、金额上下限和最多两位小数;以 `user_id + client_request_no` 幂等落库。
2. 在数据库事务外调用项目支付加密协议,明文业务参数包含 `network=NILE/MAINNET`、`amount_currency=USDT`,避免充值金额被业务币汇率转换。未传币种的原支付客户端继续使用原汇率逻辑。
3. 展示真实支付地址、准确金额、二维码、倒计时和收银台链接。每笔充值使用 `rent:<充值单号>` 支付用户标识,隔离支付金额槽位;因此需要持续补充或维护支付钱包池容量。
用户点击「创建支付单并前往支付」后,支付单就绪即自动跳转支付接口返回的 `url`。支付服务的 `payment.checkout-url` 应配置为 `https://你的前端域名/public/usdtPay`,服务端会追加 `tradeId`。旧配置的 `/public/usdtCheckout` 在生成新支付链接时自动转换为 `/public/usdtPay`。若暂未生成支付单,弹窗显示失败阶段并持续轮询,就绪后自动跳转;关闭弹窗不会触发跳转。已有订单可以从详情点击「前往支付」。
4. 支付通知必须通过 `X-Payment-Api-Key` 和 `X-Payment-Rsa-Signature` 验证,仅保存通知收件箱并返回纯文本 `ok`,不会直接修改余额。通知缺失时后台主动查单仍可完成充值。
5. 后台比较支付查询结果的订单号、交易号、网络、地址和金额,随后独立核验对应网络的已确认 USDT Transfer 日志、时间窗口、金额、收款人和交易执行结果。仅链上核验成功才可入账。
6. 同一事务内锁定充值单及资金账户,写入 TOPUP 流水、增加可用余额、标记 CREDITED。人工和自动充值共享 `TOPUP:<network>:<txhash>:<logindex>` 幂等键,避免重复入账。多实例补偿使用数据库租约与所有者校验,过期任务不能回写终态。
@@ -62,12 +63,17 @@ RENT_PAYMENT_MAINNET_MAX_AMOUNT=10000.00
| POST | `/rental/topup/create` | 请求体:`network`、字符串 `amount`、唯一 `client_request_no` |
| GET | `/rental/topup/list?network=NILE&page=1` | 当前用户指定网络记录,每页 20 条 |
| GET | `/rental/topup/{topup_no}` | 当前用户充值详情 |
| POST | `/rental/topup/{topup_no}/retry` | 核对本人原单,遵守现有租约和重试间隔,不新建支付订单 |
| POST | `/api/rental/payment/notify/{channel}` | 支付 RSA 通知,channel 为 NILE 或 MAINNET |
支付查单接口增加 `network`、`payment_address`、`payment_amount`、`expiration_time` 字段,保留原有响应字段。创建接口新增可选 `network`、`amount_currency=USDT` 参数,所有参数仍须进入 SecureClient 加密与认证。
公共收银台使用只读接口 `GET /api/v1/order/checkout/{tradeId}`。随机32位交易号应当视为支付链接访问凭据,不公开传播;接口仅返回交易号、网络、金额、地址、状态与有效期,不返回商户订单号、用户身份、回调地址或密钥。反向代理应对公共查询配置限流。支付成功展示收款结果,租赁余额仍由后台独立链上核验入账。无 `tradeId` 时保留原演示创建表单;有 `tradeId` 时直接展示现有订单,不调用演示创建接口或依赖浏览器已有缓存。
状态流转:CREATING → WAITING_PAYMENT → VERIFYING → CREDITED。创建响应不确定进入 CREATE_UNKNOWN 并使用原单号重试;支付端明确过期进入 EXPIRED。订单数据不一致、账户冻结、转账已通过其他入口入账进入 MANUAL_REVIEW。暂时网络异常和链上确认不足继续后台补偿,不生成新支付订单。浏览器关闭不影响后台核对。
仅 `rent_topup_order` 存在不代表支付创建已成功。正常情况下保存本地单后立即调用支付创建接口,无需额外操作。失败会保留原单和安全的 `payment_hint` 阶段提示,后台继续重试。支付创建已成功但查单超时时保留可支付状态与收银台入口。历史错误通道快照需要管理员核对:配置修正并不会自动覆盖已经保存的基地址、公钥或API Key。
运维可以在数据库只读检查 `topup_no/status/query_attempts/last_error/next_query_at`、支付订单及 TOPUP 流水。MANUAL_REVIEW 为人工处理终态,当前没有专用人工审核页面;不得直接改余额或删除幂等流水。确认原因并完成业务审核后,由受控运维流程恢复核对或按既有人工充值流程处理,恢复前须核对原链上事件是否已入账。
## 验证范围