成功后自动跳转 public/usdtCheckout?tradeId=...。 收银台按交易号展示网络、金额、二维码、地址及支付状态。 失败时显示处理阶段,支持使用原单重试,避免重复创建。
9.9 KiB
租赁资金账户在线充值
资金账户详情页新增「在线充值」和充值记录。用户只需选择账户网络、填写 USDT 金额,不需要输入支付 API 凭证。NILE 测试资产与主网资产严格隔离,充值不会跨网络增加余额。
部署与数据库
- 支付服务数据库执行
sql/payment_topup_upgrade.sql,为orders增加payment_network。此列是新版支付实体必需字段,即使暂不启用在线充值也须执行。脚本为一次性迁移,重复执行前先检查字段。 - 租赁服务数据库执行
sql/rent_topup_init.sql,新增rent_topup_order与rent_topup_notify,不删除历史表或数据。 - 同步部署新版支付后端、租赁后端和前端。两套后端可以部署在同一个应用实例,也可以独立部署。
- 在支付平台创建应用及有效 API 凭证,准备该应用对应的 RSA 公钥文件,确保支付钱包池有可分配地址,并将
payment.checkout-url设置为真实 HTTPS 收银台地址。
rent_topup_order 保存用户、账户、网络、请求幂等号、支付单号、金额、收款地址、支付通道公钥快照、状态、补偿租约和最终链上事件。rent_topup_notify 保存已经通过 RSA 验签的通知摘要和事件,不保存 Secret、私钥或原始签名。余额与流水继续复用 rent_account、rent_ledger。
application-rental.yml 配置
配置位于 rental.payment,默认关闭。以下是环境变量示例,替换域名和凭证后再启用:
RENT_PAYMENT_ENABLED=true
RENT_PAYMENT_NILE_ENABLED=true
RENT_PAYMENT_NILE_BASE_URL=https://pay.example.com
RENT_PAYMENT_NILE_API_KEY=<支付应用API_KEY>
RENT_PAYMENT_NILE_API_SECRET=<支付应用API_SECRET>
RENT_PAYMENT_NILE_PUBLIC_KEY=file:/opt/ruoyi/keys/nile-payment-public.pem
RENT_PAYMENT_NILE_NOTIFY_URL=https://rent.example.com/api/rental/payment/notify/NILE
RENT_PAYMENT_NILE_MIN_AMOUNT=1.00
RENT_PAYMENT_NILE_MAX_AMOUNT=10000.00
RENT_PAYMENT_MAINNET_ENABLED=false
RENT_PAYMENT_MAINNET_BASE_URL=https://pay.example.com
RENT_PAYMENT_MAINNET_API_KEY=<主网支付应用API_KEY>
RENT_PAYMENT_MAINNET_API_SECRET=<主网支付应用API_SECRET>
RENT_PAYMENT_MAINNET_PUBLIC_KEY=file:/opt/ruoyi/keys/mainnet-payment-public.pem
RENT_PAYMENT_MAINNET_NOTIFY_URL=https://rent.example.com/api/rental/payment/notify/MAINNET
RENT_PAYMENT_MAINNET_MIN_AMOUNT=1.00
RENT_PAYMENT_MAINNET_MAX_AMOUNT=10000.00
BASE_URL 是外部可访问的后端基地址,适配器追加 /api/v1/order/create-transaction 和 /api/v1/order/query。如果反向代理有路径前缀,基地址需要包含此前缀。NOTIFY_URL 必须是支付服务能访问的完整 HTTPS 地址,通道名使用大写。RSA 公钥不是 TLS 证书,也不是租赁应用凭证;应使用支付应用配置中对应的公钥。自签 TLS 证书需要导入运行租赁服务的 JVM 信任库,不能通过关闭证书验证处理。
可选超时配置:RENT_PAYMENT_CONNECT_TIMEOUT_MS=5000、RENT_PAYMENT_READ_TIMEOUT_MS=15000、RENT_PAYMENT_RECONCILE_MS=15000。单次支付 HTTP 总时限为 30 秒。后台核对需要现有 rental.rpc 正常可用及对应网络的 USDT 合约配置。
在途订单保存 API Key、公钥、基地址快照,但不保存 API Secret。存在未完成充值时应保持对应通道旧凭证有效;本实现不支持通过覆盖配置无缝轮换在途 Secret,应先完成在途核对再轮换。停止某网络通道也会暂停该网络的支付查询。
业务流程与资金安全
- 登录用户创建充值,服务端校验账户归属、ACTIVE 状态、网络、金额上下限和最多两位小数;以
user_id + client_request_no幂等落库。 - 在数据库事务外调用项目支付加密协议,明文业务参数包含
network=NILE/MAINNET、amount_currency=USDT,避免充值金额被业务币汇率转换。未传币种的原支付客户端继续使用原汇率逻辑。 - 展示真实支付地址、准确金额、二维码、倒计时和收银台链接。每笔充值使用
rent:<充值单号>支付用户标识,隔离支付金额槽位;因此需要持续补充或维护支付钱包池容量。 用户点击「创建支付单并前往支付」后,支付单就绪即自动跳转支付接口返回的url。支付服务的payment.checkout-url应配置为https://你的前端域名/public/usdtPay,服务端会追加tradeId。旧配置的/public/usdtCheckout在生成新支付链接时自动转换为/public/usdtPay。若暂未生成支付单,弹窗显示失败阶段并持续轮询,就绪后自动跳转;关闭弹窗不会触发跳转。已有订单可以从详情点击「前往支付」。 - 支付通知必须通过
X-Payment-Api-Key和X-Payment-Rsa-Signature验证,仅保存通知收件箱并返回纯文本ok,不会直接修改余额。通知缺失时后台主动查单仍可完成充值。 - 后台比较支付查询结果的订单号、交易号、网络、地址和金额,随后独立核验对应网络的已确认 USDT Transfer 日志、时间窗口、金额、收款人和交易执行结果。仅链上核验成功才可入账。
- 同一事务内锁定充值单及资金账户,写入 TOPUP 流水、增加可用余额、标记 CREDITED。人工和自动充值共享
TOPUP:<network>:<txhash>:<logindex>幂等键,避免重复入账。多实例补偿使用数据库租约与所有者校验,过期任务不能回写终态。
支付新订单保存网络快照,扫描按订单网络选择节点;历史 NULL 网络订单继续使用原全局网络配置。历史 NULL 数据不能凭猜测批量回填。
接口与状态
登录接口复用 rent:portal:view 权限,不新增菜单:
| 方法 | 路径 | 用途 |
|---|---|---|
| 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 为人工处理终态,当前没有专用人工审核页面;不得直接改余额或删除幂等流水。确认原因并完成业务审核后,由受控运维流程恢复核对或按既有人工充值流程处理,恢复前须核对原链上事件是否已入账。
验证范围
充值失败日志定位
默认 INFO 级别即可看到充值阶段日志,不需要打开全局 DEBUG。搜索 充值创建失败 或 充值核对失败,按 diagnosticId、topupNo 或 orderId 关联同一次处理。
CHANNEL_CONFIG:检查该网络启用状态及凭证是否配置,日志只记录布尔值。PUBLIC_KEY_LOAD:公钥文件读取或 RSA 解析失败;fileResource=false时检查是否遗漏file:前缀。LOCAL_ORDER_TRANSACTION:账户检查、本地充值表查询或插入失败。PAYMENT_RECONCILE:补偿租约申请等失败,包括旧表缺少lease_token字段。PAYMENT_CREATE/PAYMENT_QUERY:支付连接、TLS、认证、解析失败;结合支付 HTTP 状态和 businessCode 检查。PAYMENT_CREATE_RESPONSE_VALIDATE:支付返回单号、金额、地址、有效期或收银台地址不符合要求。CHAIN_VERIFY/LEDGER_CREDIT:链上核验或账务事务失败。
异常摘要保留异常因果类型、前五个堆栈位置及 SQLState/数据库错误码,不记录异常原文,避免 SQL 参数、支付响应、Secret、公钥正文和签名进入日志。日志定位到阶段后,再检查对应服务器文件或配置;不要向日志追加完整配置对象。
隔离测试使用 H2 事务和可控支付/链上适配器,覆盖通知验签、重复请求、超时补偿、双网络金额核对、冻结账户、共享幂等键、并发补偿及租约接管。测试不会访问真实支付账户、修改线上数据库或广播交易。上线前仍需在 NILE 配置真实支付通道完成端到端验收。