balance.topup

Sent when funds are added to an environment.

WEBHOOK balance.topup

Example

{
  "id": "evt_8aZqRm4yT3vK7pNxJ2bH9c",
  "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

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

Show child attributes

Response

2XX

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