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

# Mobile Money

> Send funds instantly to supported Mobile Money wallets in Tanzania.

# Mobile Money

The Mobile Money Disbursement API enables you to send money from your SplashPay wallet to supported Mobile Money networks through a single API.

Supported networks include:

* Vodacom M-Pesa
* Airtel Money
* Mixx by Yas
* HaloPesa
* EzyPesa
* TTCL Pesa

***

## Endpoint

```http theme={null}
POST /disbursements/mobile-money
```

***

## Authentication

Every request must include your API credentials.

| Header          | Required | Description               |
| --------------- | :------: | ------------------------- |
| X-API-KEY       |     ✅    | Merchant API Key          |
| X-API-SECRET    |     ✅    | Merchant API Secret       |
| Idempotency-Key |     ✅    | Unique request identifier |
| Content-Type    |     ✅    | application/json          |

***

## Example Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --request POST \
      --url https://api.splashpay.co.tz/api/v1/disbursements/mobile-money \
      --header "Content-Type: application/json" \
      --header "X-API-KEY: pk_live_xxxxxxxxx" \
      --header "X-API-SECRET: sk_live_xxxxxxxxx" \
      --header "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
      --data '{
          "reference":"PAYOUT-100001",
          "recipient_phone":"255747123456",
          "recipient_name":"John Doe",
          "amount":1000,
          "currency":"TZS",
          "network":"MPESA",
          "remarks":"Salary Payment",
          "metadata":{
              "employee_id":"EMP-1001"
          }
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch(
      "https://api.splashpay.co.tz/api/v1/disbursements/mobile-money",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-API-KEY": process.env.SPLASHPAY_KEY,
          "X-API-SECRET": process.env.SPLASHPAY_SECRET,
          "Idempotency-Key":
            crypto.randomUUID(),
        },
        body: JSON.stringify({
          reference: "PAYOUT-100001",
          recipient_phone: "255747123456",
          recipient_name: "John Doe",
          amount: 1000,
          currency: "TZS",
          network: "MPESA",
          remarks: "Salary Payment",
          metadata: {
            employee_id: "EMP-1001"
          }
        }),
      }
    );

    const data = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import uuid
    import requests

    response = requests.post(
        "https://api.splashpay.co.tz/api/v1/disbursements/mobile-money",
        headers={
            "X-API-KEY": "pk_live_xxxxxxxxx",
            "X-API-SECRET": "sk_live_xxxxxxxxx",
            "Idempotency-Key": str(uuid.uuid4()),
            "Content-Type": "application/json",
        },
        json={
            "reference": "PAYOUT-100001",
            "recipient_phone": "255747123456",
            "recipient_name": "John Doe",
            "amount": 1000,
            "currency": "TZS",
            "network": "MPESA",
            "remarks": "Salary Payment",
            "metadata": {
                "employee_id": "EMP-1001"
            }
        },
    )

    print(response.json())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $client = new \GuzzleHttp\Client();

    $response = $client->post(
        'https://api.splashpay.co.tz/api/v1/disbursements/mobile-money',
        [
            'headers' => [
                'X-API-KEY' => 'pk_live_xxxxxxxxx',
                'X-API-SECRET' => 'sk_live_xxxxxxxxx',
                'Idempotency-Key' => uniqid(),
            ],
            'json' => [
                'reference' => 'PAYOUT-100001',
                'recipient_phone' => '255747123456',
                'recipient_name' => 'John Doe',
                'amount' => 1000,
                'currency' => 'TZS',
                'network' => 'MPESA',
                'remarks' => 'Salary Payment',
                'metadata' => [
                    'employee_id' => 'EMP-1001'
                ]
            ],
        ]
    );

    echo $response->getBody();
    ```
  </Tab>
</Tabs>

***

## Request Body

| Field            | Type    | Required | Description                                                                             |
| ---------------- | ------- | :------: | --------------------------------------------------------------------------------------- |
| reference        | string  |     ✅    | Unique merchant payout reference                                                        |
| recipient\_phone | string  |     ✅    | Recipient phone number (255XXXXXXXXX)                                                   |
| recipient\_name  | string  |     ✅    | Recipient full name                                                                     |
| amount           | decimal |     ✅    | Amount to send                                                                          |
| currency         | string  |     ✅    | Currency (TZS)                                                                          |
| network          | string  |     ✅    | Mobile money network (MPESA, MIXX\_BY\_YAS, AIRTEL\_MONEY, HALOPESA, EZYPESA, TTCLPESA) |
| remarks          | string  |     ✅    | Payment description                                                                     |
| metadata         | object  |    No    | Additional merchant data                                                                |

***

## Example Response

```json theme={null}
{
  "status": "success",
  "code": "DISBURSEMENT_INITIATED",
  "message": "Disbursement initiated successfully.",
  "data": {
    "reference": "PAYOUT-100001",
    "amount": "1000.00",
    "fee": "150.00",
    "total_amount": "1150.00",
    "currency": "TZS",
    "recipient_name": "John Doe",
    "recipient_phone": "255747123456",
    "channel": "MOBILE_MONEY",
    "network": "MPESA",
    "status": "processing",
    "provider": "selcom",
    "remarks": "Salary Payment",
    "created_at": "2026-07-05T10:20:00Z"
  },
  "request_id": "2c4b4959-45e8-4cf5-93b3-c74fd4c8d57f"
}
```

***

## Transaction Status

| Status     | Description                    |
| ---------- | ------------------------------ |
| pending    | Request accepted               |
| processing | Submitted to provider          |
| paid       | Funds delivered successfully   |
| failed     | Provider rejected the transfer |
| cancelled  | Transaction cancelled          |

***

## Verify Recipient

To reduce failed transactions, verify the recipient before initiating a payout.

```http theme={null}
POST /disbursements/name-lookup
```

***

## Error Codes

| Code                  | Description                             |
| --------------------- | --------------------------------------- |
| INVALID\_NETWORK      | Unsupported Mobile Money network        |
| INVALID\_PHONE        | Invalid recipient phone number          |
| INSUFFICIENT\_BALANCE | Merchant wallet balance is insufficient |
| DUPLICATE\_REFERENCE  | Reference already exists                |
| DUPLICATE\_REQUEST    | Duplicate Idempotency-Key               |
| PROVIDER\_ERROR       | Provider returned an error              |

***

## Best Practices

<Steps>
  <Step title="Use unique references">
    Generate a unique payout reference for every disbursement.
  </Step>

  <Step title="Include an Idempotency-Key">
    Prevent duplicate payouts when retrying requests.
  </Step>

  <Step title="Verify recipients">
    Use the Name Lookup API before initiating payouts whenever possible.
  </Step>

  <Step title="Listen for webhooks">
    Use webhook notifications to receive the final transaction status instead of polling.
  </Step>
</Steps>