Skip to main content
WEBHOOK
balance.topup
{
  "id": "evt_8aZqRm4yT3vK7pNxJ2bH9c",
  "created": 123,
  "data": {
    "object": {
      "environment_id": "<string>",
      "available": 123,
      "held": 123,
      "currency": "USD"
    }
  }
}

Documentation Index

Fetch the complete documentation index at: https://mintfax.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Authorization
string
header
required

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.

​
id
string
required

Event identifier (evt_-prefixed). Stable across retry attempts.

Example:

"evt_8aZqRm4yT3vK7pNxJ2bH9c"

​
type
enum<string>
required

Event type. Always balance.topup for this delivery.

Available options:
balance.topup
​
created
integer
required

Unix epoch seconds when the event was generated.

​
data
object
required

Response

2XX

Acknowledged. mintfax treats any 2xx response as a successful delivery.

Last modified on May 14, 2026