跳到正文

API

本页内容

负载

读取带版本的 webhook 信封，以及 data 中完整的账单、转出或通道充值资源快照。

每个 webhook body 都是一个带版本的信封。data 对象与对应状态 API 返回的商户侧资源契约相同，因此你的处理器可以直接应用完整快照，而不是合并部分增量。三种资源都是如此：账单、转出和通道充值共用同一个信封、同一条负载规则。

信封

字段 类型 契约
event_id string 稳定的带前缀 ID（evt_…），与 X-Webhook-Id 相同，重试和重放期间不变
event_type string 事件目录中的一个值
version integer 负载模式版本。当前版本为 1
occurred_at Unix 秒 资源流转发生的时间；与投递时间戳不同，重试时不变
data object 本事件的完整账单、转出或通道充值快照

event_id 标识一次投递：某个端点收到的某一次流转的副本。订阅同一事件的两个端点，对同一笔付款会拿到两个不同的 evt_ 值。业务身份是 data 里的资源标识——inv_…、wdr_… 或 pcd_…——它在不同端点、不同流转和重放之间都相同。同一笔钱按业务标识只记一次，同一次投递按 event_id 只处理一次。

在开始昂贵处理前，先存下 event_id、event_type、version 和原始 body。对集成不支持的模式版本直接拒绝，不要猜测其结构。

账单负载

示例：invoice.paid。

{
  "event_id": "evt_J7EEYeL9pZJukfj2c5OQ44",
  "event_type": "invoice.paid",
  "version": 1,
  "occurred_at": 1739281200,
  "data": {
    "invoice_id": "inv_5CcyDYmMUGtzYL10q0Iimr",
    "project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
    "status": "paid",
    "is_final": true,
    "is_test": false,
    "payment_url": "https://checkout.paymos.io/invoice/inv_5CcyDYmMUGtzYL10q0Iimr",
    "order": {
      "external_id": "order-12345",
      "client_id": "customer-67890",
      "amount": "100.00",
      "currency": "USD"
    },
    "payment": {
      "currency": "USDT",
      "network": "TRC20",
      "chain_id": 728126428,
      "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "expected": "50.00",
      "address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
      "exchange_rate": "2.00",
      "paid": "50.00",
      "remaining": "0",
      "fee": "0.50",
      "net": "49.50",
      "transfers": [
        {
          "tx_hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
          "amount": "50.00",
          "status": "confirmed",
          "created_at": 1739281020,
          "confirmed_at": 1739281200,
          "required_confirmations": 19,
          "estimated_confirmation_at": 1739281080,
          "explorer_url": "https://tronscan.org/#/transaction/abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
        }
      ]
    },
    "expires_at": 1739284200,
    "completed_at": 1739281200,
    "created_at": 1739277600,
    "updated_at": 1739281200
  }
}

账单的 data 遵循 获取账单 响应。当前状态下尚不存在的字段按 JSON 契约为 null 或省略；以 status 和 is_final 作为状态权威。

转出负载

示例：withdrawal.completed。

{
  "event_id": "evt_CbYeOgBp9Kt2U3j74fxxLl",
  "event_type": "withdrawal.completed",
  "version": 1,
  "occurred_at": 1739281200,
  "data": {
    "withdrawal_id": "wdr_7K2M9P4Q8R1X5Z3A0bC2dE",
    "external_order_id": "payout-12345",
    "status": "completed",
    "is_final": true,
    "is_test": false,
    "amount": "25.00",
    "fee": "0.50",
    "currency": "USDT",
    "network": "TRC20",
    "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
    "tx_hash": "7f8a9b0c1d2e3f4a5b6c7d8e9f00112233445566778899aabbccddeeff001122",
    "explorer_url": "https://tronscan.org/#/transaction/7f8a9b0c1d2e3f4a5b6c7d8e9f00112233445566778899aabbccddeeff001122",
    "created_at": 1739277600,
    "completed_at": 1739281200
  }
}

转出的 data 遵循 获取转出 响应。有可追踪的链上交易时填充 tx_hash 和 explorer_url；它们不能替代 status。

通道充值负载

示例：payment_channel.deposit.confirmed。

{
  "event_id": "evt_J7EEYeL9pZJukfj2c5OQ44",
  "event_type": "payment_channel.deposit.confirmed",
  "version": 1,
  "occurred_at": 1767225930,
  "data": {
    "id": "pcd_8ScRvL4jNq2XkB7mTfZdWu",
    "payment_channel_id": "pc_2QhKZv6mRt9WdA3nYpLbXf",
    "project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
    "payment_channel_external_id": "customer-42",
    "status": "confirmed",
    "is_final": true,
    "is_test": false,
    "currency": "USDT",
    "network": "TRC20",
    "chain_id": 728126428,
    "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "gross": "100",
    "fee": "1",
    "net": "99",
    "applied_fee_percent": 1.0,
    "customer_fee_percent": 0,
    "tx_hash": "9f4c1b7e30ad52c8ef6a1d84b0c39f27a5e6d138f4b90c72ae51d63b8407fc25",
    "transfer_id": "9f4c1b7e30ad52c8ef6a1d84b0c39f27a5e6d138f4b90c72ae51d63b8407fc25:41a614f803b6fd780986a42c78ec9c7f77e6ded13c:41c9f6a2b7d0138e54ca3b91f6072ed48a5c1e93b7:0",
    "source_address": "TW9s4RkAqBnLpVdX2ChYzUeGm7QfKt3NbZ",
    "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
    "block_height": 68421905,
    "first_included_block_timestamp": 1767225900,
    "explorer_url": "https://tronscan.org/#/transaction/9f4c1b7e30ad52c8ef6a1d84b0c39f27a5e6d138f4b90c72ae51d63b8407fc25",
    "created_at": 1767225870,
    "updated_at": 1767225930,
    "confirmed_at": 1767225930
  }
}

充值的 data 遵循 获取通道充值 响应。以 status 和 is_final 作为状态权威；applied_fee_percent 和 customer_fee_percent 是为这条充值冻结的费率，之后改定价也不会动它们。

三个充值事件带的是同一个对象，所以一条 confirming 负载就已经给出通道、付款人标识、金额和链上凭据。confirming 和 reorged 属于提示，可能不按顺序到达——不要让它们把一条你已经知道是 confirmed 的充值退回去。

兼容性

  • 新增字段可能在版本不变的情况下出现。忽略你的处理器不用的字段。
  • 同一负载版本内，既有字段的含义不变。
  • 把标识符和十进制金额当字符串处理。不要把带前缀 ID 解析成 UUID，也不要把金额解析成二进制浮点。
  • 在解析 JSON 之前对原始字节验证签名。重新序列化对象会改变被签名的输入。
Webhook 事件 验证签名