从创建订单，到可靠处理通知

1. 准备项目

登录控制台，创建项目，配置自有收款地址与 HTTPS 通知地址，生成项目 API Key。API Secret 仅在生成时展示，必须保存在商户服务端。首版仅支持 TRC20 / BEP20 USDT。

2. 创建与查询订单

POST /v1/orders 需要 Idempotency-Key。重试保留同一幂等键和原始请求正文；首次返回 201，重放返回 200，同键不同内容返回 409。

{
  "merchant_order_id": "shop_example_001",
  "amount": "20.00",
  "currency": "USDT",
  "network": "TRC20"
}

首次建单响应包含 order_id、状态和 checkout_url。幂等响应保存期限过后可能只返回 order_id 和 checkout_recovery_required；此时先查原订单，不能换幂等键重复建单。使用服务端返回的最终应付金额，不能只按商品原价付款。可省略 network，让买家在项目和套餐支持的网络中选择；也可用 allowed_networks 限定候选网络。若同时提供，network 必须包含在 allowed_networks 中。

GET /v1/orders/{id} 查询订单，POST /v1/orders/{id}/cancel 取消尚未进入确认或已付状态且未到期的订单，需携带 Idempotency-Key 和空 JSON 正文。金额始终使用十进制字符串。

3. 服务端请求签名

请求头：WP-Key-ID、WP-Timestamp（Unix 秒）、WP-Nonce、WP-Signature。

METHOD
path
canonical_query
sha256_hex(raw_body)
timestamp
nonce

六行使用单个 LF 连接，末尾没有换行；以项目 Secret 计算 HMAC-SHA256 小写 hex。空查询仍保留对应空行。签名覆盖实际发送的原始正文，不能重新序列化后验签。

查询参数按 RFC3986 编码，空格用 %20，保留重复键，按编码后的键、值排序。时间窗口 ±300 秒；每次请求使用新的 16–128 位字母、数字、下划线或短横线 nonce，业务重试也必须刷新时间、nonce 与签名。

4. 验证付款通知后履约

通知头为 WP-Webhook-ID、WP-Webhook-Timestamp、WP-Webhook-Signature。签名值为 v1=<64 位小写 hex>。

v1
<event_id>
<timestamp>
 + 原始 body 字节

使用该通知地址绑定的 Secret 验证 HMAC-SHA256，检查 ±300 秒时间窗口、正文与请求头的 event_id 一致，使用恒定时间比较。通知会重复投递，接收方需要持久化事件唯一约束，把接收记录和履约任务放在同一事务中。

付款事件必须核对订单、币种、网络、金额和付款来源。页面返回成功、买家上传凭证、人工认领都不能直接推导为链上自动付款。HTTP 应答成功也不等于商品已交付。

接口范围与异常处理

下载文件仅包含商户服务端签名 API：身份查询、建单、查单、取消。控制台与运营登录接口不属于商户接入协议。 查询已付订单时还需检查 payment_risk；review_required 表示需要核对，不能仅凭已付状态继续自动履约。账单/订单关闭后付款应进入异常核对，不能自行标记成功或自动退款。Secret 仅保存在商户服务器，不要粘贴到网页。