Prepaid Balance Updated
Sent when prepaid funds are frozen, settled, released, debited, credited, or returned to payable. Book from this event.
Event Types
| Event | When Emitted |
|---|---|
merchant.balance.updated | This merchant's prepaid balance changed |
Delivery Contract
- We send a
POSTrequest withapplication/jsonto your configured endpoint, with a 10-second timeout. - Any 2xx response acknowledges receipt. Non-2xx responses and timeouts trigger retries with backoff.
- Four request headers:
content-type·z-signature·z-event-id·z-event-type。 - Deduplicate by
z-event-id— the same event may be delivered more than once.
There are no amounts, asset codes, card number fragments or risk-control reasons. This is a security boundary: the webhook endpoint is your service, whose transport and storage we cannot guarantee.
The GET /v1/<resource>/{id} endpoint applies API key, scope and on-behalf-of checks. Fetch details using data.id;
do not use webhook payloads as the source of amounts for your ledger.
Event Details
merchant.balance.updated
This merchant's prepaid balance changedSent 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.
{
"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"
}
}Signature Verification
The signature verification procedure is the same for all events. See Webhook Overview; use the Signature Debugger to compare signing strings character by character.