How TZS credits and mobile-money top-ups fit together
A top-up starts a payment request; it doesn't mean the payment has completed. Ngamia records model usage and payments in a workspace ledger, while mobile-money confirmation arrives asynchronously.
Start the payment with an idempotency key
The top-up endpoint uses your account session and an amount in TZS. Send an Idempotency-Key so retrying the same request doesn't accidentally create a second payment. A verified phone number is required for the payment flow.
POST https://api.ngamia.cc/v1/payments/topup
Idempotency-Key: <unique-request-id>
{ "amount_tzs": 5000 }Wait for the provider confirmation
The response begins as pending while the customer approves the mobile-money prompt. Credits are added only after the payment provider confirms completion. Show the pending state in your UI and check payment status or balance after approval.
Read usage from the workspace ledger
Model requests create usage records and debit credits according to current model pricing. Keep the balance visible and link users to transaction history when they ask where credits went. Read current prices from the catalog rather than promising a fixed rate on a marketing page.