商户资金水位

资金低水位提醒、充值提现暂停及补款恢复通知。

事件类型

事件	什么时候发
`merchant.balance.waterline`	全部下游商户资金池水位状态变化

投递约定

我方向你配置的端点发 POST，application/json，超时 10 秒。
回任意 2xx 即视为收到。 非 2xx 或超时会按退避重投。
请求头四个：content-type · z-signature · z-event-id · z-event-type。
按 z-event-id 去重 —— 同一条事件可能到达多次。

事件体只带 ID 与状态

没有金额、没有资产代码、没有卡号的任何片段、没有风控原因。这不是省字节 —— webhook 端点是你的服务，我方没有办法保证它的传输与存储；而 GET /v1/<资源>/{id} 那条路径上有 API Key、scope、代理会员三层校验。要详情就拿 data.id 回查， 别指望从事件体里读出金额来记账。

逐条

merchant.balance.waterline 全部下游商户资金池水位状态变化

什么时候发

按币种汇总全部真实下游商户的可用资金，跨越提醒、暂停或恢复阈值时向下游发送。scope 固定为 all_downstream_merchants；不含沙盒与平台自营资金，汇总金额仅平台后台可见。halted=true 暂停新增卡充值、卡转出及提现；商户补款和在途结算继续。halted=false 仅表示该币种水位未暂停；任一其他币种暂停或人工、风控限制仍然有效。同一状态变化重试使用相同 event_id；后收到的旧事件不能覆盖较新的 status_version。

事件体

{
  "event_id": "evt_11111111222243338444555555555555",
  "event_type": "merchant.balance.waterline",
  "created_at": "2026-09-09T08:00:00Z",
  "merchant_id": "acme",
  "livemode": true,
  "data": {
    "object": "merchant_balance",
    "id": "USD",
    "external_member_id": "",
    "status": "halt",
    "status_version": 1788940800000,
    "asset": "USD",
    "scope": "all_downstream_merchants",
    "halted": true
  }
}

验签

验签方式与所有事件一致，见 Webhook 概览；可以用签名调试器逐字符比对签名串。