> For the complete documentation index, see [llms.txt](https://developers.klasha.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.klasha.com/accepting-payments/payments-api/mobile-money.md).

# Mobile money

Follow these steps to accept payment using our mobile money API:

* Initiate the Payment via API
* Customer validates OTP on their device(optional)
* Check Status via API

> You would need to pass, as header the `x-auth-token`. This can be obtained from your merchant dashboard → Settings → Generate API keys → **Merchant public key.**

### Coverage

{% hint style="info" %}
The gateway parameter on the request api should be set to anyone of the following currency below for their respective country.
{% endhint %}

<table><thead><tr><th width="207.828125">Country</th><th width="155.953125">Country Code</th><th width="112.48828125">Currency/Gateway</th><th>Network</th></tr></thead><tbody><tr><td>Democratic Republic of the Congo</td><td>COD</td><td>CDF</td><td>vodacom, airtel, orange, mpesa</td></tr><tr><td>Republic of the Congo</td><td>COG</td><td>XAF</td><td>airtel, mtn</td></tr><tr><td>Kenya</td><td>KEN</td><td>KES</td><td>mpesa</td></tr><tr><td>Uganda</td><td>UGA</td><td>UGX</td><td>airtel, mtn</td></tr><tr><td>Senegal</td><td>SEN</td><td>XOF</td><td>free, orange</td></tr><tr><td>Tanzania<mark style="color:red;">*</mark></td><td>TZS</td><td>TZS</td><td>airtel, tigo, halotel </td></tr><tr><td>Ivory Coast (Côte d'Ivoire)</td><td>CIV</td><td>XOF</td><td>mtn, orange</td></tr><tr><td>Rwanda</td><td>RWA</td><td>RWF</td><td>airtel, mtn</td></tr><tr><td>Zambia</td><td>ZMB</td><td>ZMW</td><td>mtn, zamtel</td></tr><tr><td>Sierra Leone</td><td>SLE</td><td>SLE</td><td>orange</td></tr><tr><td>Gabon</td><td>GAB</td><td>XAF</td><td>airtel</td></tr><tr><td>Ghana</td><td>GHS</td><td>GHS</td><td>airtel</td></tr><tr><td>Cameroon</td><td>CMR</td><td>XAF</td><td>mtn, orange</td></tr></tbody></table>

{% hint style="info" %} <sup>*<mark style="color:red;">\*</mark>*</sup><sup>*TZS transactions amount must not have decimals*</sup>
{% endhint %}

### Initiate the Payment

> <mark style="color:yellow;">**POST**</mark> - {{env\_url}}/pay/aggregators/{{gateway}}/mobilemoney/v3

{% hint style="info" %}
**NB**: All requests sent to this api must be encrypted. See encryption algorithm [**here**](/accepting-payments/payments-api.md#encryption-algorithm)
{% endhint %}

**Headers**

| Name                                           | Value                    |
| ---------------------------------------------- | ------------------------ |
| Content-Type                                   | `application/json`       |
| x-auth-token<mark style="color:red;">\*</mark> | Your merchant public key |

**Params**

{% hint style="info" %}
[See  for details on the url params](#user-content-fn-1)[^1]
{% endhint %}

**Request Body (plain version)**

> * <sup>*The payload must be encrypted before sending*</sup>
> * <sup>*Test phone numbers can be found*</sup> [<sup>*here*</sup>](https://developers.klasha.com/accepting-payments/test-payments#mobile-money-phone-numbers)

```json
{
   "fullname": "Francisca Reuben",
   "email": "fran@matrix.io",
   "phone_number": "260953456700",
   "tx_ref": "de43d7a1-569c-4348-abd8-75246e81d500", // must be UUID generated
   "network": "mtn",
   "description": "payment for airpod",
   "country": "ZMB",
   "amount": "10",
   "currency": "ZMW",
   "rate": "1",
   "paymentType": "woo", // should be left has woo
   "sourceCurrency": "ZMW",
   "sourceAmount": "10",
   "rememberMe": false,
   "productType": "COLLECTION"
}
```

**Request Body (encrypted)**

```json
{
    "message": "encrypted-body"
}
```

**Response**

The customer will need to enter the OTP sent to their provided phone number when the payment is initiated and the message in the response message is "Please enter otp".

{% tabs %}
{% tab title="200 (pending otp)" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "message": "success",
        "error": null,
        "data": {
            "amount": "10",
            "charged_amount": "10",
            "currency": "ZMW",
            "message": "Please enter otp",
            "status": "pending",
            "customer": {
                "country": "ZMB",
                "name": "Francisca Reuben",
                "phone_number": "260763456789",
                "operator": "mtn"
            }
        }
    }
}
```

{% endtab %}

{% tab title="200 (pending)" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "message": "success",
        "error": null,
        "data": {
            "amount": "10",
            "charged_amount": "10",
            "currency": "ZMW",
            "message": "Transaction in progress",
            "status": "pending",
            "customer": {
                "country": "ZMB",
                "name": "Francisca Reuben",
                "phone_number": "260763456789",
                "operator": "mtn"
            }
        }
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "message": "failed",
    "error": "Bad Request",
    "data": {
        "status": "error",
        "error": "failed",
        "message": "Duplicate reference provided"
    }
}
```

{% endtab %}
{% endtabs %}

### Check Status

Use the Transaction status API [here](/misc/transaction-status.md) to check the status of the transaction by passing your transaction reference as `tnx_ref` in the request body.

[^1]:


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.klasha.com/accepting-payments/payments-api/mobile-money.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.