---
title: "An automatic top-up failed"
method: POST
path: "balance.reload_failed"
tags: ["Webhooks"]
---

# An automatic top-up failed

`POST balance.reload_failed` (webhook)

We POST this event to every active endpoint subscribed to it (webhook.test only to the endpoint you test). Respond with any 2xx within ten seconds; anything else is retried with backoff for up to 24 hours, in eight attempts. The event id stays the same on retries, so you can skip duplicates.

## Headers

- `Hypamoon-Signature` string, required

## Payload

- BalanceReloadFailedEvent: Sent when an automatic top-up failed. Carries balance_eur, threshold_eur and reload. After three failures in a row automatic top-up is switched off.
  - `id` string, required: The id of the event, evt_ plus 32 hex characters. It stays the same on retries.
  - `type` 'balance.reload_failed', required
  - `created_at` string, date-time, required: When the event happened.
  - `data` object, required
    - `balance_eur` number, required: The balance at the moment of the event, in euro excluding VAT.
    - `threshold_eur` number: The threshold for automatic top-up. With balance.low and balance.reload_failed.
    - `transaction` Transaction: One line in the ledger of the prepaid balance. The same shape in GET /balance and the balance webhooks.
      - `id` string, required: The id of the transaction.
      - `type` 'top_up' | 'charge' | 'refund' | 'adjustment', required: top_up: money added with a payment. charge: usage deducted. refund: a charge given back (an SMS the carrier refused, for example). adjustment: a correction by Hypamoon support.
      - `source` 'payment' | 'sms' | 'call' | 'number' | 'chat' | 'site' | 'support', required: What caused it: a payment, an SMS, a call, a number, a chat reply of the assistant, site requests above what the plan includes, or Hypamoon support.
      - `amount_eur` number, required: The amount in euro excluding VAT, with a sign: positive for a top-up or refund, negative for a charge. Up to four decimals.
      - `balance_after_eur` number, required: The balance right after this transaction, in euro excluding VAT.
      - `description` string, required: What it was for, in a few words.
      - `quantity` number, nullable, required: How many units, like 2 SMS segments or 3 minutes. Null for a top-up.
      - `unit` string, nullable, required: The unit of quantity, like segment, minute or month. Null for a top-up.
      - `reference_id` string, nullable, required: The id of what caused it: a message, a call, a number or a payment.
      - `created_at` string, date-time, required: When the transaction was booked.
    - `reload` Reload: An automatic top-up that failed.
      - `id` string, required: The id of the top-up payment.
      - `amount_eur` number, required: The amount it tried to add, excluding VAT.
      - `status` string, required: The status of the payment, like failed, canceled or expired.
      - `failure_reason` string, nullable, required: A short code for why it failed, or null.
      - `created_at` string, date-time, required: When the top-up started.

## Acknowledgement `2XX`

Received. Any 2xx counts.

---

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