Payments — Ngamia Docs

A top-up has two stages: Ngamia creates a payment and sends a mobile-money prompt; the payment service later confirms or rejects it. The initial response is not proof that credits have been added. Keep provider implementation details and payment secrets on the server.

Start a top-up

POST/v1/payments/topupJWT

{ "amount_tzs": 2000 }

Requirement	Details
Credential	JWT access token.
Amount	`amount_tzs` must be greater than zero.
Phone	The account phone number must be verified.
Retry header	Always send a unique `Idempotency-Key` per logical top-up.

curl -X POST https://api.ngamia.cc/v1/payments/topup \\
  -H "Authorization: Bearer $NGAMIA_ACCESS_TOKEN" \\
  -H "Content-Type: application/json" \\
  -H "Idempotency-Key: $(uuidgen)" \\
  -d '{"amount_tzs": 2000}'

Initial response

{
  "id": "1839f442-94dc-4479-8fcf-b350e83abfda",
 
  "amount_tzs": 2000,
  "credits_granted": 2000,
  "status": "pending",
  "created_at": "2026-07-14T12:45:24Z"
}

The response starts with status: "pending". Tell the user to approve the USSD prompt on their phone, then poll the payment record or balance. Do not grant credits in your application from the initial response alone.

Track the payment

GET/v1/payments/{id}JWT

Poll every few seconds with a bounded timeout, or read the balance after the user confirms the prompt. Stop polling when the payment reaches a terminal status.

Status	Meaning	Application action
`pending`	Prompt sent; confirmation is still outstanding.	Keep the payment in a waiting state.
`completed`	Funds settled and credits granted.	Refresh the balance and allow the original operation.
`failed`	The user cancelled or the provider rejected the payment.	Show the failure and offer a new top-up.
`expired`	The confirmation window elapsed.	Show the expiry and offer a new top-up.
`reversed`	A previously completed payment was reversed.	Refresh the balance and flag the account for review.

List payments

GET/v1/paymentsJWT

Use this endpoint to display recent payment history. GET /v1/payments/{id} returns 404 not_found when the payment does not belong to the authenticated account.

Retry safely

Keep the idempotency key with the payment record. If the network fails after the top-up request, retry with the same key. Ngamia replays the original result after completion instead of creating a second top-up.

The request body is not compared when a key is reused. Generate a new key for every new top-up, and never reuse a key from an older payment.

If top-up creation returns 403 forbidden, verify the account phone number first (add/verify it with POST /v1/me/phone — see Profile & workspaces). A payment-service failure can return 502; keep the Ngamia payment id, log the request_id, and retry only when it is safe to do so. Never log the full phone number, payment credentials, or provider reference.