Z Zise Developers 简体中文

merchant.balance.updated

This merchant's prepaid balance changed

When Emitted

Sent when this merchant's own prepaid balance is frozen, settled, released, debited directly, credited, or returned to payable. Book from this event. Card events only say which step the card reached and do not carry prepaid amounts. data.status is the reason: frozen, settled, released (including a failed top-up that returns the freeze to available), debited (available debited directly for an issue fee, quick-verification fee, or card spend fee, with no prior freeze). For a non-self-operated merchant, a card spend fee is taken from the card balance first. Any remainder is taken 1:1 from that merchant's available USD, USDT, USDC, or USD1, in that order. asset is the asset actually debited and amount is that asset's integer amount. When the debit relates to a card transaction, related_type is card_transaction, data.id uses the ctx_ prefix, and external_member_id is the member's id in the merchant's own system. Use this debit to collect the fee from your own user. credited (available increased), refunded (returned to payable; available and frozen are unchanged), payable_settled (payable moved into available: available increases and payable decreases by the same amount; this is not new money). A card-cancellation fee refund sends refunded first, then payable_settled after the transfer. data.id stays the same application. A rejected merchant payout also sends payable_settled: the amount locked in payable returns to available. amount, available, frozen, available_delta, frozen_delta, and payable_delta are integer strings in that asset's ledger scale. available and frozen are the balances after this posting. status_version is that asset's balance version; an older event must not overwrite a newer snapshot. If a settlement does not spend the whole freeze, frozen_delta is the full freeze decrease, available_delta is the remainder returned to available, and amount is the net that left prepaid. data.id is the related id. related_type card_application uses a cap_ prefix; card_topup uses ctp_, a first top-up uses first:, card_transaction uses ctx_, and card_withdrawal uses cwd_. Retries of the same journal and asset use the same event_id.

This event is not initiated by an API call

Triggered by a scheduled job or a provider callback.

Payload

{
  "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"
  }
}

Payload Fields

FieldTypeDescription
idstringUse this for deduplication. evt_… remains unchanged when the same event is redelivered.
typestringAlways merchant.balance.updated
created_atstringTime the event was created (RFC3339), not its delivery time. It is unchanged on redelivery.
data.objectstringObject type; determines which endpoint to query with data.id
data.idstringObject ID; use it to retrieve details.
data.statusstringTreat unrecognized values as unknown and raise an alert; do not fall back to “processing”
data.status_versionnumberMonotonically increasing; use it to discard older states that arrive late.

Signature Verification and Deduplication

Verify the signature against the raw request body bytes. Do not parse and reserialize the JSON: your JSON library may change key order or whitespace, which changes the signature and can look like a key configuration error.

// Node · Run before parsing JSON
const raw = await readRawBody(req);            // Buffer / string; do not use parsed req.body
const expect = crypto.createHmac("sha256", WEBHOOK_SECRET).update(raw).digest("hex");
const got = req.headers["z-signature"];        // Format: t=<unix>,v1=<hex>
if (!timingSafeEqual(expect, parseV1(got))) return res.status(400).end();

// Deduplicate using the envelope id, not data.id
if (await seen(JSON.parse(raw).id)) return res.status(200).end();

For the full procedure, including timestamp tolerance and redelivery semantics, see Webhook Guide.