How to detect a successful wallet top-up via webhook

To confirm a paid wallet top-up succeeded, check the wallet_transaction.updated webhook for both status: "settled" and transaction_status: "purchased". Checking status alone is not enough, because status: "settled" is also set on free granted credits.

Lago fires wallet_transaction.created with status: "pending" when a paid top-up is initiated, then wallet_transaction.updated with the final status once the payment is processed.

How wallet top-up webhooks work

• Source of the top-up. The source field tells you what triggered it: manual, interval (a recurring top-up), or threshold (a balance threshold crossing).

• Failed payments. If the payment fails instead of succeeding, Lago fires the same wallet_transaction.updated webhook with status: "failed", so a single webhook subscription can handle both outcomes.

• Wallet details included. Both wallet_transaction.created and wallet_transaction.updated include the full wallet object in the payload, including the wallet name. You don't need a separate API call to look up the wallet.

• Granted (free) credits. These behave differently: they arrive already settled in the wallet_transaction.created payload and never trigger a wallet_transaction.updated event at all. This is why filtering on transaction_status: "purchased" matters, since it's what distinguishes a paid top-up from a free credit grant.

What to use for payment confirmation

Lago also sends an invoice.paid_credit_added webhook when the top-up invoice is finalized. This is not a payment confirmation. By default, the invoice is finalized before the payment is processed, so invoice.paid_credit_added fires even if the payment later fails.

The exception is a wallet configured with invoice_requires_successful_payment: true, a premium feature. In that case the invoice stays open until the payment succeeds, so the webhook only fires after a successful payment.

Because this behavior depends on configuration, don't rely on invoice.paid_credit_added as a payment-success signal. The wallet_transaction.updated check at the top of this article is the one to use instead.

Troubleshooting

If you're not receiving the wallet webhooks you expect, first confirm your endpoint is registered under Developers → Webhooks in the Lago UI, then check the webhook messages list there for full payload inspection. The Activity logs tab (Developers → Activity logs) shows an audit trail of account activity but not webhook payloads; the Events tab is for ingested usage events, not webhook deliveries. Neither substitutes for checking the webhook messages list directly.

This article reflects guidance drawn from customer case resolutions. It is not officially supported documentation and may not apply to all situations.