Merchant Funding Levels

Low-balance alerts, top-up and withdrawal suspension, and recovery notifications after replenishment.

Event Types

Event	When Emitted
`merchant.balance.waterline`	Aggregate downstream merchant funding-pool level changed

Delivery Contract

We send a POST request with application/json to 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.

Event payloads contain only IDs and status

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.waterline Aggregate downstream merchant funding-pool level changed

When Emitted

Sent to downstream merchants when the available funds of all real downstream merchants, aggregated by asset, cross an alert, pause, or resume threshold. scope is always all_downstream_merchants. Sandbox and platform-direct funds are excluded; aggregate amounts are visible only in the platform administration console. halted=true pauses new card top-ups, card withdrawals, and withdrawals; merchant funding and in-flight settlements continue. halted=false only means that this asset’s funding level is not paused. Pauses for any other asset, manual restrictions, and risk-control restrictions still apply. Retries of the same change reuse event_id; an older event arriving later must not overwrite a newer status_version.

Payload

{
  "event_id": "evt_11111111222243338444555555555555",
  "event_type": "merchant.balance.waterline",
  "created_at": "2026-09-09T08:00:00Z",
  "merchant_id": "acme",
  "livemode": true,
  "data": {
    "object": "merchant_balance",
    "id": "USD",
    "external_member_id": "",
    "status": "halt",
    "status_version": 1788940800000,
    "asset": "USD",
    "scope": "all_downstream_merchants",
    "halted": true
  }
}

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.