支付结果回调（Webhook）

当订单变为 PAID 或 FAILED 时，平台将异步向你配置的 HTTPS 地址发送 POST。

回调目标

1. 商户在平台侧配置的 Webhook URL（若已开通）
2. 建单时传入的 notify_url（若有）

同一事件、同一请求体、同一套签名；每个 URL 独立重试最多 3 次。若两处为同一 URL，只投递一次。

物流事件（仅开放 API 建单的订单）

在已支付且保存了有效追踪单号后：

event	含义
SHIPPED	首次填写有效追踪号
LOGISTICS_UPDATED	承运商、追踪号或发货备注相对上次发生变化

请求头

头	说明
Content-Type	application/json
X-Open-Api-Timestamp	Unix 秒级时间戳（字符串）
X-Open-Api-Signature	sha256=<hex>，见下

签名校验

使用完整 API 密钥（整串 sk....）作为 HMAC 密钥：

signingPayload = `${timestamp}.${rawBody}`
signature = HMAC-SHA256(api_key_utf8, signingPayload)

请求头值为：X-Open-Api-Signature: sha256= + 十六进制小写签名。

验签时请使用原始 body 字符串（与收到的字节一致），不要先 parse 再 stringify。

伪代码示例

const crypto = require("crypto");

function verify(req, apiKey) {
  const timestamp = req.headers["x-open-api-timestamp"];
  const header = req.headers["x-open-api-signature"]; // sha256=...
  const rawBody = req.rawBody; // 原始字符串
  const expected =
    "sha256=" +
    crypto
      .createHmac("sha256", apiKey)
      .update(`${timestamp}.${rawBody}`)
      .digest("hex");
  return header === expected;
}

请求体示例

支付结果（order 不含 shipping）

{
  "event": "PAID",
  "event_id": "<uuid>",
  "occurred_at": "2026-04-13T12:00:00.000Z",
  "order": {
    "id": "...",
    "merchant_order_id": "...",
    "charge_code": "...",
    "status": "PAID",
    "amount": 99.0,
    "currency": "USD",
    "description": "...",
    "paid_at": "...",
    "created_at": "...",
    "expires_at": "...",
    "payment_url": "https://...",
    "settled_via": "ONLINE",
    "crypto_payment": null
  }
}

USDT 结算成功时 settled_via 为 CRYPTO，并带有 crypto_payment 对象（见 USDT 结算说明）。

物流事件（含 shipping）

{
  "event": "SHIPPED",
  "event_id": "<uuid>",
  "occurred_at": "2026-04-13T12:00:00.000Z",
  "order": {
    "id": "...",
    "merchant_order_id": "...",
    "charge_code": "...",
    "status": "PAID",
    "amount": 99.0,
    "currency": "USD",
    "description": "...",
    "paid_at": "...",
    "created_at": "...",
    "expires_at": "...",
    "payment_url": "https://...",
    "shipping": {
      "shipping_carrier": "DHL",
      "tracking_no": "1234567890",
      "shipping_note": null,
      "shipped_at": "2026-04-13T11:00:00.000Z"
    }
  }
}

event 取值：PAID | FAILED | SHIPPED | LOGISTICS_UPDATED。

幂等与重试

• 同一订单可能收到多次投递尝试；请用 order.id + event（或 event_id）做幂等。物流事件可结合 shipping.tracking_no 等去重。
• 平台侧最多 3 次 HTTP 尝试（间隔递增）。请尽快返回 2xx。