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。
由 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"
}
}
事件体字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 去重用这个。evt_…,同一事件重投时不变。 |
type | string | 固定为 merchant.balance.updated |
created_at | string | 事件产生时刻(RFC3339)。不是投递时刻 —— 重投时它不变。 |
data.object | string | 对象类型,决定 data.id 该拿去查哪个端点 |
data.id | string | 对象 ID,拿它回查详情 |
data.status | string | 认不出的值按未知处理并告警,不要 fallback 成「处理中」 |
data.status_version | number | 单调递增,用它把慢到的旧状态丢掉 |
验签与去重
验签用原始请求体字节,不要先解析再重新序列化 —— 你的 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 指南。