# 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**](https://developers.klasha.com/accepting-payments/payments-api/..#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](https://developers.klasha.com/misc/transaction-status) to check the status of the transaction by passing your transaction reference as `tnx_ref` in the request body.

[^1]: