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

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

The question should be specific, self-contained, and written in natural language.
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.