Files
usdt/docs/rental/merchant-order-callback-demo.md
T

5.4 KiB

租赁API下单与商户回调示例

首页立即租赁

PROXY_ACCOUNT 的“我的套餐”点击立即租赁,填写资源接收地址、应用 API Key / Secret、租期(秒)、API对接基地址、可选回调地址、商户订单号。先获取预计费用,再点击确认费用并租赁。移除了该按钮对后台 rent:order:create 权限的依赖,实际下单仍由应用凭证验签和所属用户的套餐绑定、账户余额共同校验。

Secret只在弹窗内存中用于签名,关闭弹窗清除,不写浏览器缓存、不作为请求参数发送。浏览器签名使用Web Crypto,需要HTTPS页面或localhost。应用Secret只在签发时展示,遗失时请重新签发。不要填节点凭证。所填凭证决定实际应用和扣费用户;填写当前账户自己的应用凭证。

默认API基地址为当前前端配置的代理前缀,例如 /prod-api。远程对接填写 https://rent.example.com,不含 /api/rental/v1/create;远程服务需允许浏览器当前来源、POST和X-Rent-*请求头。反向代理应将前缀去除,使服务端看到原始 /api/rental/v1/quote 或 /api/rental/v1/create 路径。时钟需同步。

报价与计费

POST /api/rental/v1/quote 和 create 都要求 X-Rent-Key、X-Rent-Timestamp(毫秒)、X-Rent-Nonce、X-Rent-Signature。HMAC协议保持不变:API域、POST、服务端实际路径、原始UTF-8请求体SHA256,按换行连接后HMAC-SHA256,小写十六进制。签名后不得重新序列化JSON。

示例请求体(两接口共用,create额外带expected_amount):

{
  "package_id": 1,
  "duration_seconds": 7200,
  "receiver_address": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
  "merchant_order_no": "WEB_UNIQUE_ORDER_NO",
  "notify_url": "https://merchant.example.com/api/rental/v1/demo/callback/async"
}

报价返回 amount(精确十进制字符串)、currency=USDT、duration_seconds、network、resource_quantity。确认下单传 expected_amount,服务端重新计算并比较,价格变更则拒绝。所有费用使用BigDecimal。

租期为套餐基础租期的1至720个整数倍,总售价、供应商毛收入同比例增加,资源数量保持不变。例如基础3600秒、售价3USDT,7200秒为6USDT。该规则同时作用于登录入口及外部API;不传租期继续使用基础租期,兼容现有调用。实际资源回收按订单租期快照执行。请求超时后使用相同商户单号及原参数重试;不要更换单号重复扣费。

回调地址只允许公网HTTPS、443端口、无查询参数,不允许内网或回环目标。留空沿用应用默认地址。订单创建成功是同步API响应,不代表链上已经交付;以查询API及已验签异步通知为准。当前协议没有浏览器return_url跳转回调。

同步、异步验签Controller

实现:RentalCallbackDemoController,默认关闭,仅演示商户接收端。部署于同一云端项目中,或连同验签工具、事务仓储迁入商户项目。

先执行 sql/rent_callback_demo.sql 创建独立演示收件箱;租赁基础表(含rent_nonce)仍需先初始化。然后通过外部配置启用,凭证必须是该应用当前ACTIVE凭证:

rental:
  callback-demo:
    enabled: true
    api-key: ${RENT_DEMO_API_KEY:}
    api-secret: ${RENT_DEMO_API_SECRET:}

接口使用既有 /api/rental/v1/** 公开入口,但每个请求都验证WEBHOOK域签名、Key、60秒时间窗、随机数和原始请求体;没有关闭认证。不要在日志输出Secret、签名或请求体。轮换应用凭证后同步更新接收端凭证;生产建议支持受控的多Key过渡。

接口 处理流程 成功确认
POST /api/rental/v1/demo/callback/sync 验签→随机数防重放→event_no去重→同步事务记录处理结果 事务提交后返回HTTP 200、纯文本ok
POST /api/rental/v1/demo/callback/async 验签→随机数防重放→event_no去重→持久化待处理收件箱 持久化提交后返回HTTP 200、纯文本ok;每3秒扫描事务处理

无效签名返回400,持久化失败返回503,不返回ok。并发事件冲突会回滚并让云端用新随机数重投;重复事件内容一致则确认,内容冲突拒绝。同一HTTP报文重放不通过随机数唯一约束。异步处理不使用易丢失的内存队列,重启后扫描继续。

示例业务仅记录验签事件/消费标记,不执行真实商户履约或入账。接入实际业务时,应保存所需通知字段,在同一事务中按本地订单号及event_no更新业务,并利用order_event_sequence防止乱序状态回退;外部副作用使用事务发件箱。不要照搬演示标记替代实际业务处理。

租赁云端仅在回调HTTP 200且正文严格为ok时确认,失败按既有任务重试,达到上限保留DEAD记录供处理。应用当前有效凭证用于签名,WEBHOOK域与API域严格隔离。

验证

JDK8下64项租赁测试通过,覆盖已签名报价/下单、报价不扣费、租期计费、冻结资金、幂等重试、价格变化拒绝,以及回调原文/路径/域/时间窗验签、落库确认、重复事件及异步消费。前端ESLint、Vue模板/CSS解析、独立HMAC及UTF8签名校验通过,staging完整构建成功;保留其他模块已有导出缺失和资源体积警告。实际浏览器、公网回调、数据库迁移及链上交付尚需部署后联调。