Z Zise Developers English

merchant.balance.updated

本商户预付余额变动

何时发

这个商户自己的预付发生冻结、结算、解冻、直接扣款、入账或退回应付时发送。 用这一条记账。卡业务事件只说明卡到了哪一步,不携带备付金金额。 data.status 是原因:frozen 冻结,settled 结算,released 解冻(含充值失败把冻结退回可用), debited 直接扣可用(开卡费、快捷认证费、消费手续费,没有先冻结)。 非自营商户的消费手续费先扣卡内余额,不够的部分按 USD、USDT、USDC、USD1 以 1:1 扣该商户对应资产的可用预付,一种不够再扣下一种。asset 是实际扣到的资产, amount 是该资产的定点金额。关联到卡交易时 related_type 为 card_transaction, data.id 带 ctx_ 前缀,external_member_id 是该会员在商户侧的用户 ID。 商户用这条扣款向自己的用户收费。 credited 入账(可用增加),refunded 退回应付(销卡退款进应付,可用和冻结此时不变), payable_settled 应付划入可用(可用增加、应付等额减少,不是新的入金)。 销卡开卡费退款先发 refunded,划转完成再发 payable_settled,data.id 仍是同一张申请单。 商户提现被退回时也发 payable_settled,锁在应付里的金额回到可用。 amount、available、frozen、available_delta、frozen_delta、payable_delta 都是该资产的定点整数字符串。 available 与 frozen 是这笔过账之后的余额。status_version 是该资产余额版本,后到的旧版本不能覆盖更新的余额快照。 结算若有没花完的冻结,frozen_delta 为整段冻结的减少,available_delta 为退回可用的余量,amount 是真正离开预付的净额。 data.id 是关联单号。related_type 为 card_application 时 id 带 cap_ 前缀; card_topup 为 ctp_ 前缀,开卡首充为 first: 前缀;card_transaction 为 ctx_;card_withdrawal 为 cwd_。 同一张凭证的同一个资产重试使用相同 event_id。

这条事件不由任何 API 调用发起

由 cron 或上游回调触发。

事件体

{
  "event_id": "evt_11111111222243338444555555555556",
  "event_type": "merchant.balance.updated",
  "created_at": "2026-10-19T08:00:00Z",
  "merchant_id": "acme",
  "livemode": true,
  "data": {
    "object": "merchant_balance",
    "id": "ctp_11111111-2222-4333-8444-555555555555",
    "external_member_id": "",
    "status": "frozen",
    "status_version": 4,
    "asset": "USDT",
    "amount": "1000000",
    "available": "9000000",
    "frozen": "1000000",
    "available_delta": "-1000000",
    "frozen_delta": "1000000",
    "payable_delta": "0",
    "related_type": "card_topup"
  }
}

事件体字段

字段类型说明
idstring去重用这个。evt_…,同一事件重投时不变。
typestring固定为 merchant.balance.updated
created_atstring事件产生时刻(RFC3339)。不是投递时刻 —— 重投时它不变。
data.objectstring对象类型,决定 data.id 该拿去查哪个端点
data.idstring对象 ID,拿它回查详情
data.statusstring认不出的值按未知处理并告警,不要 fallback 成「处理中」
data.status_versionnumber单调递增,用它把慢到的旧状态丢掉

验签与去重

验签用原始请求体字节,不要先解析再重新序列化 —— 你的 JSON 库与我方的键顺序、空格几乎一定不同,重新序列化出来的签名一定对不上, 而那个错误长得像「密钥配错了」。

// Node · 放在解析 JSON 之前
const raw = await readRawBody(req);            // Buffer / string,别用已解析的 req.body
const expect = crypto.createHmac("sha256", WEBHOOK_SECRET).update(raw).digest("hex");
const got = req.headers["z-signature"];        // 形如 t=<unix>,v1=<hex>
if (!timingSafeEqual(expect, parseV1(got))) return res.status(400).end();

// 去重:用信封的 id,不是 data.id
if (await seen(JSON.parse(raw).id)) return res.status(200).end();

完整做法(含时间戳容差与重投语义)见 Webhook 指南。