预付余额变动
备付金冻结、结算、解冻、直接扣款、入账或退回应付时发送。用这一条记账。
事件类型
| 事件 | 什么时候发 |
|---|---|
merchant.balance.updated | 本商户预付余额变动 |
投递约定
- 我方向你配置的端点发
POST,application/json,超时 10 秒。 - 回任意 2xx 即视为收到。 非 2xx 或超时会按退避重投。
- 请求头四个:
content-type·z-signature·z-event-id·z-event-type。 - 按
z-event-id去重 —— 同一条事件可能到达多次。
没有金额、没有资产代码、没有卡号的任何片段、没有风控原因。这不是省字节 ——
webhook 端点是你的服务,我方没有办法保证它的传输与存储;
而 GET /v1/<资源>/{id} 那条路径上有 API Key、scope、
代理会员三层校验。要详情就拿 data.id 回查,
别指望从事件体里读出金额来记账。
逐条
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。
{
"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"
}
}验签
验签方式与所有事件一致,见 Webhook 概览; 可以用签名调试器逐字符比对签名串。