---
title: "Balance charged event"
method: POST
path: "balance.charged"
tags: ["Webhook Events"]
---

# Balance charged event

`POST balance.charged` (webhook)

Balance billing only. Funds were added to the balance by card: by someone (`trigger: manual`) or by the auto top-up rule (`trigger: auto_top_up`).

### When it fires

Once per card payment into the balance, when it is credited. Stripe emails the billing owner its receipt for the charge.

### Payload notes

`topup.amountCents` was added to the balance; the card was charged `topup.chargedCents`, which is that plus `topup.taxCents` (VAT, 0 when none applies). The invoice and receipt are at `GET /v1/balance/top-ups/{topupId}/invoice` and `/receipt`.

### Who receives it

The billing owner's endpoints, like `balance.low`. Restricted keys need the `money` resource group.

## Payload

- WebhookPayloadBalanceCharged
  - `id` string, required: Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource.
  - `test` boolean: Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do.
  - `event` 'balance.charged', required
  - `topup` object, required
    - `id` string, required: The top-up id, as in GET /v1/balance (`recentTopups`) and its invoice and receipt endpoints.
    - `trigger` 'manual' | 'auto_top_up', required: `manual`: someone added funds in Billing or through the API. `auto_top_up`: the auto top-up rule charged the card.
    - `amountCents` integer, required: Added to the balance, in USD cents.
    - `taxCents` integer, required: VAT charged on top, in USD cents (0 when none applies).
    - `chargedCents` integer, required: What the card was charged, in USD cents: amount plus tax.
    - `currency` 'usd', required
    - `card` object, nullable, required
      - `brand` string, required: Card brand as Stripe names it, e.g. visa or mastercard.
      - `last4` string, nullable, required
  - `balance` object, required
    - `spendableCents` integer, required: What pay-per-use can spend after the top-up, in USD cents.
  - `timestamp` string, date-time, required: UTC time at which Zernio generated this event. Retries and redeliveries keep the original value.

## Acknowledgement `200`

Webhook received successfully

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) - [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/a79c233ebf22?raw)