{
"id": "evt_8aZqRm4yT3vK7pNxJ2bH9c",
"type": "balance.topup",
"created": 123,
"data": {
"object": {
"environment_id": "<string>",
"available": 123,
"held": 123,
"currency": "USD"
}
}
}Event types
balance.topup
Sent when funds are added to an environment.
WEBHOOK
balance.topup
{
"id": "evt_8aZqRm4yT3vK7pNxJ2bH9c",
"type": "balance.topup",
"created": 123,
"data": {
"object": {
"environment_id": "<string>",
"available": 123,
"held": 123,
"currency": "USD"
}
}
}This event is part of the published catalog but is not yet emitted by mintfax. The schema on this page is the target so you can build against it now. Subscribing to
balance.topup today will not return an error, but no deliveries will arrive until the producer ships.When it will fire
When credit is added to an environment, whether the addition is manual (someone clicked Top Up in the dashboard or an admin called the API) or automatic (auto-top-up triggered against the low-balance threshold). One event fires per credit addition. A single top-up that brings the balance well above the threshold produces one event, not several.What your handler should do
- Update any internal accounting that tracks mintfax credits.
- For auto-top-up flows, this is the confirmation that the charge succeeded against your billing source and credit was added.
- For manual top-ups, this is mainly a notification - useful for audit and for finance dashboards that want to reconcile mintfax balance against expected spend.
Authorizations
API key as Bearer token. Use an account key (mfx_acct_...) for
/account/* endpoints, and an environment key (mfx_test_... for
sandbox, mfx_live_... for live) for /environment/*, /faxes,
/webhooks, and /events.
Body
application/json
Event delivery to your subscribed webhook endpoint.
Webhook delivery for balance.topup.
Event identifier (evt_-prefixed). Stable across retry attempts.
Example:
"evt_8aZqRm4yT3vK7pNxJ2bH9c"
Event type. Always balance.topup for this delivery.
Available options:
balance.topup Unix epoch seconds when the event was generated.
Show child attributes
Show child attributes
Response
2XX
Acknowledged. mintfax treats any 2xx response as a successful delivery.
Last modified on July 14, 2026