Top up an account

Activity diagram

Request observed in the web app

The Studio sends JSON { "amount_tzs": Number(amount) } to POST /api/ngamia/v1/payments/topup with credentials and a fresh UUID Idempotency-Key. The proxy streams the response and status back. The UI tells the user to follow the instructions sent to their phone.

This request initiates a real mobile money payment prompt. The Music API proxy does not validate the amount, collect a phone number, settle the payment, or refresh balance automatically. Those rules belong to the Ngamia API/payment integration. Check the upstream payment contract for accepted amounts, providers, settlement states, and idempotency guarantees. A client should not treat a successful initiation response as confirmed funds; re-read balance or payment status after provider confirmation.