> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centipidbilling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AzamPay

> Configure AzamPay mobile money checkout for Tanzania, including the callback password that payments depend on.

# 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.

<Warning>
  **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.
</Warning>

## Configure the gateway

<Steps>
  <Step title="Open Settings → Payments → AzamPay">
    Select AzamPay from the payment marketplace.
  </Step>

  <Step title="Choose the environment">
    **Environment** (required) is `Sandbox` or `Production`. Use sandbox while
    testing.
  </Step>

  <Step title="Enter the app identity">
    **App name** (required) must match the AzamPay portal exactly. **Client ID**
    and **client secret** (required) come from the same place.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Enter the callback password">
    Required in practice for live payments — see the warning above.
  </Step>

  <Step title="Run a controlled test payment">
    Pay a small amount and confirm both halves: the wallet prompt arrives,
    **and** the payment lands in the ledger.
  </Step>
</Steps>

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Authorization">
    The payer approves on their handset.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](/billing/payment-gateways/credentials-reference).