接入

接口约定

接口地址、响应格式、金额、幂等、重试与频率限制。

接口地址

text

/open/v1

沙箱与生产共用同一域名，环境由签名所用的 API Key 决定；一把 Key 只能看到本环境的订单（其他环境返回 ORDER_NOT_FOUND），out_order_no 在各环境内分别唯一。

响应格式

响应使用真实的 HTTP 状态码和统一结构：

json

{
  "trace_id": "6c1f0b9a3e2d4f5a",
  "status_code": 200,
  "message": "success",
  "data": { "id": "…", "status": "CREATED" }
}

json

{
  "trace_id": "6c1f0b9a3e2d4f5a",
  "status_code": 422,
  "message": "The amount exceeds the app's payment limit.",
  "error_code": "LIMIT_EXCEEDED"
}

用 error_code 判断分支，不要用 message（英文，可能变化）。
记录 trace_id，联系客服时提供。
INVALID_REQUEST 的 message 会说明哪个字段不合法，便于开发调试。

数据格式

类型	格式
金额	字符串，USDT，正数，输入最多 2 位小数（`"5"`、`"5.5"`、`"5.50"`），输出固定 2 位。不要用浮点数。
币种	只支持 `"USDT"`（否则 `CURRENCY_NOT_SUPPORTED`）
时间	RFC 3339 UTC，如 `2026-11-07T09:30:00Z`
ID	HTP 订单 `id` 为 UUID。你的 `out_order_no` / `out_refund_no`：1–64 位 `[A-Za-z0-9_-]`
用户	OIDC `sub` 字符串（最长 128）

幂等

创建类接口（POST /payments、POST /payments/{id}/refunds、POST /payouts）必须带 Idempotency-Key。

相同 Key + 相同请求体 → 重放首次成功的响应，不会重复创建。
相同 Key + 不同请求体 → 409 IDEMPOTENCY_KEY_REUSED。
首个请求仍在处理时用同一 Key → 409 IDEMPOTENCY_IN_PROGRESS，稍后重试。
失败的请求不会占用该 Key，重试会重新执行。

每个业务操作生成一次 Key（例如与订单一起保存），每次重试都复用它。每次重试仍需新的 X-Nonce、X-Timestamp 和签名。

out_order_no 是第二道保障：换了 Idempotency-Key 但 out_order_no 已使用，返回 ORDER_ALREADY_EXISTS。

重试与超时

情况	处理
创建请求网络错误或超时	用相同 Idempotency-Key 重试，或查询 `GET /open/v1/orders?out_order_no=…`
`5xx`、`REPLAY_PROTECTION_UNAVAILABLE`、`IDEMPOTENCY_IN_PROGRESS`	指数退避重试
`429 TOO_MANY_REQUESTS`	等待 `Retry-After` 秒
其他 `4xx`	不要原样重试 —— 先修正请求

频率限制

签名请求按 App 限流（默认每分钟 600 次）。超限返回 429，带 Retry-After: 60。

请求体大小

请求体最大 64 KB。