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.
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
| Field | Type | Description |
|---|---|---|
id | string | Use this for deduplication. evt_… remains unchanged when the same event is redelivered. |
type | string | Always merchant.balance.updated |
created_at | string | Time the event was created (RFC3339), not its delivery time. It is unchanged on redelivery. |
data.object | string | Object type; determines which endpoint to query with data.id |
data.id | string | Object ID; use it to retrieve details. |
data.status | string | Treat unrecognized values as unknown and raise an alert; do not fall back to “processing” |
data.status_version | number | Monotonically 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.