AzamPay

Collect payments with AzamPay

AZAMPAY pushes a payment request to the payer’s mobile money wallet through AzamPay’s MNO checkout. The payer authorizes on their handset, and AzamPay confirms the result on a callback.

Available to ISPs in Tanzania (TZ), alongside ClickPesa, PalmPesa, PawaPay, PesaPal, Relworx, ZenoPay, PayPal, and DPO.

Before you start

1. Complete AzamPay merchant onboarding in an account owned by the ISP.
2. From the AzamPay portal collect the app name, client ID, client secret, the authenticator base URL, the checkout base URL, and the callback password.
3. Decide whether you are configuring sandbox or production — the base URLs differ, and mixing them is the most common setup failure.

Caution

Set the callback password before taking live payments. The form marks it optional, because sandbox may not send one. In production the callback verification fails closed: with no callback password saved, every AzamPay callback is rejected as unauthorized, so payers are charged and never provisioned. There is no partial mode — configure it, or do not go live.

Configure the gateway

1. Open Settings → Payments → AzamPay

   Select AzamPay from the payment marketplace.

2. Choose the environment

   Environment (required) is Sandbox or Production. Use sandbox while testing.

3. Enter the app identity

   App name (required) must match the AzamPay portal exactly. Client ID and client secret (required) come from the same place.

4. Enter both base URLs

   Authenticator base URL and checkout base URL (both required, full URLs) must match the environment you selected. Checkout requests are sent to <checkout base URL>/azampay/mno/checkout.

5. Enter the callback password

   Required in practice for live payments — see the warning above.

6. Run a controlled test payment

   Pay a small amount and confirm both halves: the wallet prompt arrives, and the payment lands in the ledger.

Credentials

Field	Required	Notes
Environment	Yes	Sandbox or Production.
App name	Yes	Exactly as configured at AzamPay.
Client ID	Yes	Also checked against the callback when AzamPay includes one.
Client secret	Yes	Secret.
Authenticator base URL	Yes	Full URL, matching the environment.
Checkout base URL	Yes	Full URL, matching the environment.
Callback password	Marked optional	Secret. Callbacks are rejected without it — treat it as required for production.

The six fields above the callback password are what gate the switch; the callback password does not, which is exactly why it is easy to miss.

Callback URLs

Register https://<your-host>/api/azampay/callback in the AzamPay portal.

Callbacks are accepted only when the password in the callback body matches your saved callback password. When AzamPay includes a client id, that must match too. Repeated callbacks for a transaction already recorded are ignored rather than double-credited.

What the payer must provide

• A Tanzanian mobile money number, normalized before the request is sent.
• A provider choice. The payer picks their wallet at checkout: Airtel, Tigo, Halopesa, Azampesa, or Mpesa. A request with no supported provider is refused before it reaches AzamPay.

Authorization happens on the handset, so no AzamPay domain needs to be added to the captive walled garden.

How a payment completes

1. Request

   Centipid Billing authenticates against the authenticator base URL, caches the token, and posts the checkout with the amount, currency, provider, and a unique external id.

2. Authorization

   The payer approves on their handset.

3. Confirmation

   AzamPay posts the result to the callback. Only success credits the payment; any other status is recorded against the transaction and nothing is provisioned.

Troubleshooting

Symptom	What it means	What to do
“Please select a supported AzamPay provider.”	The checkout carried no provider, or one AzamPay does not support.	Have the payer pick Airtel, Tigo, Halopesa, Azampesa, or Mpesa.
“AzamPay credentials are incomplete. Please update the payment settings.”	One of the required fields is blank.	Complete every field in Settings → Payments.
“Unable to authenticate with AzamPay at the moment. Please try again.”	The authenticator rejected the client ID or secret.	Re-copy both. Confirm the authenticator base URL matches the selected environment.
“AzamPay is unreachable right now…”	The checkout endpoint could not be connected to.	Check outbound connectivity and the checkout base URL.
“AzamPay rejected the payment request.”	AzamPay refused it; its own message is shown when it sends one.	Read the message. Check the app name matches the portal exactly.
Prompts succeed, ledger stays empty	Callbacks are being rejected — most often no callback password saved.	Save the callback password from the AzamPay portal, then re-test.
Sandbox works, production does not	The base URLs still point at sandbox.	Change both base URLs together with the environment.

For every gateway’s fields in one place, see the credential reference.