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

> Accept Mobile Money payments from all major Tanzanian mobile networks using the SplashPay Collections API.

# Mobile Money

The Mobile Money API allows merchants to initiate customer payments using Tanzania's leading mobile money providers through a single integration.

Supported networks include:

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

SplashPay automatically routes the payment request to the appropriate provider based on the customer's mobile number.

***

## Endpoint

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

***

## Base URLs

<Tabs>
  <Tab title="Sandbox">
    ```bash theme={null}
    https://sandbox-api.splashpay.co.tz/api/v1
    ```

    Use this environment for development and testing.
  </Tab>

  <Tab title="Production">
    ```bash theme={null}
    https://api.splashpay.co.tz/api/v1
    ```

    Use this environment for live transactions.
  </Tab>
</Tabs>

***

# Request Body

| Field           | Type   | Required | Description                                   |
| --------------- | ------ | :------: | --------------------------------------------- |
| amount          | number |    Yes   | Payment amount                                |
| currency        | string |    Yes   | Currency code. Must be `TZS`.                 |
| reference       | string |    Yes   | Unique merchant reference                     |
| phone           | string |    Yes   | Customer phone number in international format |
| customer\_name  | string |    Yes   | Customer full name                            |
| customer\_email | string |    Yes   | Customer email address                        |
| metadata        | object |    No    | Additional merchant data                      |

***

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.splashpay.co.tz/api/v1/payments/mobile-money \
    --header "Content-Type: application/json" \
    --header "X-API-KEY: pk_live_xxxxxxxxxxxxx" \
    --header "X-API-SECRET: sk_live_xxxxxxxxxxxxx" \
    --header "Idempotency-Key: UniqueKey123" \
    --data '{
      "amount": 1000,
      "currency": "TZS",
      "reference": "INV-1234`",
      "phone": "255712345678",
      "customer_name": "John Doe",
      "customer_email": "john.doe@example.com"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.splashpay.co.tz/api/v1/payments/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({
        amount: 1000,
        currency: 'TZS',
        reference: 'INV-1234',
        phone: '255712345678',
        customer_name: 'John Doe',
        customer_email: 'john.doe@example.com',
      }),
    }
  );

  const payment = await response.json();

  console.log(payment);
  ```

  ```python Python theme={null}
  import uuid
  import requests

  response = requests.post(
      "https://api.splashpay.co.tz/api/v1/payments/mobile-money",
      headers={
          "Content-Type": "application/json",
          "X-API-KEY": "YOUR_API_KEY",
          "X-API-SECRET": "YOUR_API_SECRET",
          "Idempotency-Key": str(uuid.uuid4())
      },
      json={
          "amount": 1000,
          "currency": "TZS",
          "reference": "INV-1234",
          "phone": "255712345678",
          "customer_name": "John Doe",
          "customer_email": "john.doe@example.com"
      }
  )

  print(response.status_code)
  print(response.json())
  ```

  ```php PHP theme={null}
  use Illuminate\Support\Facades\Http;
  use Illuminate\Support\Str;

  $response = Http::withHeaders([
      'X-API-KEY' => env('SPLASHPAY_KEY'),
      'X-API-SECRET' => env('SPLASHPAY_SECRET'),
      'Idempotency-Key' => (string) Str::uuid(),
  ])->post(
      'https://api.splashpay.co.tz/api/v1/payments/mobile-money',
      [
          'amount' => 1000,
          'currency' => 'TZS',
          'reference' => 'INV-1234',
          'phone' => '255712345678',
          'customer_name' => 'John Doe',
          'customer_email' => 'john.doe@example.com',
      ]
  );

  return $response->json();
  ```

  ```dart Dart theme={null}
  import 'dart:convert';
  import 'package:http/http.dart' as http;
  import 'package:uuid/uuid.dart';

  Future<void> initiatePayment() async {
    final response = await http.post(
      Uri.parse(
        'https://api.splashpay.co.tz/api/v1/payments/mobile-money',
      ),
      headers: {
        'Content-Type': 'application/json',
        'X-API-KEY': 'YOUR_API_KEY',
        'X-API-SECRET': 'YOUR_API_SECRET',
        'Idempotency-Key': const Uuid().v4(),
      },
      body: jsonEncode({
        'amount': 1000,
        'currency': 'TZS',
        'reference': 'INV-1234',
        'phone': '255712345678',
        'customer_name': 'John Doe',
        'customer_email': 'john.doe@example.com',
      }),
    );

    print(response.body);
  }
  ```
</CodeGroup>

***

## Successful Response

If the request is accepted successfully, SplashPay returns a `200 OK` response with the payment details.

```json theme={null}
{
  "status": "success",
  "code": "PAYMENT_INITIATED",
  "message": "Payment initiated",
  "data": {
    "merchant_id": 2,
    "customer_name": "John Doe",
    "customer_email": "john.doe@example.com",
    "customer_phone": "255712345678",
    "reference": "INV-1234",
    "amount": "1000.00",
    "fee": 15.00,
    "net_amount": 985.00,
    "currency": "TZS",
    "source": "api",
    "payment_method": "mobile_money",
    "provider": "selcom",
    "provider_reference": "S20618089300",
    "status": "pending",
    "metadata": null,
    "created_at": "2026-07-03T10:28:57Z",
    "processing_at": "2026-07-03T13:28:57Z"
  },
  "meta": [],
  "request_id": "85323840-963b-4464-897f-12613975b8e3"
}
```

***

## Response Fields

| Field                     | Type           | Description                                                |
| ------------------------- | -------------- | ---------------------------------------------------------- |
| `status`                  | string         | Indicates whether the API request was successful.          |
| `code`                    | string         | Machine-readable response code.                            |
| `message`                 | string         | Human-readable response message.                           |
| `data.merchant_id`        | integer        | Unique merchant identifier.                                |
| `data.customer_name`      | string         | Customer's full name.                                      |
| `data.customer_email`     | string         | Customer's email address.                                  |
| `data.customer_phone`     | string         | Customer's phone number in international format.           |
| `data.reference`          | string         | Merchant's unique payment reference.                       |
| `data.amount`             | decimal        | Payment amount requested.                                  |
| `data.fee`                | decimal        | SplashPay processing fee.                                  |
| `data.net_amount`         | decimal        | Amount after deducting the processing fee.                 |
| `data.currency`           | string         | Transaction currency (`TZS`).                              |
| `data.source`             | string         | Source of the transaction (e.g. `api`).                    |
| `data.payment_method`     | string         | Payment method used to initiate the transaction.           |
| `data.provider`           | string         | Payment service provider handling the transaction.         |
| `data.provider_reference` | string         | Provider's unique transaction reference.                   |
| `data.status`             | string         | Current transaction status.                                |
| `data.metadata`           | object \| null | Additional merchant-defined metadata.                      |
| `data.created_at`         | string         | Timestamp when the transaction was created (ISO-8601).     |
| `data.processing_at`      | string \| null | Timestamp when processing began.                           |
| `meta`                    | array          | Additional response metadata. Reserved for future use.     |
| `request_id`              | string         | Unique request identifier for troubleshooting and support. |

<Warning>
  A successful initiation **does not mean the customer has completed payment**. The initial transaction status is typically `pending`. You should wait for a webhook notification or query the Payment Status endpoint to determine the final payment outcome.
</Warning>

***

# Payment Status

| Status     | Description                       |
| ---------- | --------------------------------- |
| pending    | Waiting for customer confirmation |
| processing | Payment is being processed        |
| success    | Payment completed successfully    |
| failed     | Payment failed                    |
| cancelled  | Customer cancelled payment        |
| expired    | Payment expired                   |

***

## Sample Webhook Payload

When a payment reaches a final state, SplashPay sends an HTTP `POST` request to your configured webhook endpoint.

```json theme={null}
{
  "event": "payment.success",
  "created_at": "2026-06-24T09:59:24.430757Z",
  "data": {
    "reference": "INV-1234",
    "amount": "1000.00",
    "currency": "TZS",
    "status": "success",
    "customer_name": "John Doe",
    "customer_email": "john.doe@example.com",
    "customer_phone": "255712345678",
    "channel": "TIGOPESATZ",
    "provider_reference": "1769142083",
    "metadata": null
  }
}
```

***

## Webhook Fields

| Field                     | Type           | Description                                              |
| ------------------------- | -------------- | -------------------------------------------------------- |
| `event`                   | string         | Event type sent by SplashPay.                            |
| `created_at`              | string         | ISO-8601 timestamp when the webhook was generated.       |
| `data.reference`          | string         | Merchant payment reference.                              |
| `data.amount`             | decimal        | Payment amount.                                          |
| `data.currency`           | string         | Transaction currency (`TZS`).                            |
| `data.status`             | string         | Final payment status.                                    |
| `data.customer_name`      | string         | Customer's full name.                                    |
| `data.customer_email`     | string         | Customer's email address.                                |
| `data.customer_phone`     | string         | Customer's phone number.                                 |
| `data.channel`            | string         | Provider channel or network used to process the payment. |
| `data.provider_reference` | string         | Provider transaction reference.                          |
| `data.metadata`           | object \| null | Additional merchant-defined metadata.                    |

***

## Supported Events

SplashPay currently sends the following payment events:

| Event               | Description                                        |
| ------------------- | -------------------------------------------------- |
| `payment.success`   | Payment completed successfully.                    |
| `payment.failed`    | Payment failed.                                    |
| `payment.cancelled` | Payment was cancelled by the customer or provider. |
| `payment.expired`   | Payment request expired before completion.         |

<Warning>
  Webhook notifications may be delivered more than once. Your webhook endpoint should be **idempotent** by checking the payment `reference` before processing the event.
</Warning>

<Info>
  Always verify the webhook signature before processing the payload and return an HTTP **200 OK** response after successful processing to prevent unnecessary retries.
</Info>

***

# Error Responses

## Invalid Request

```json theme={null}
{
    "success": false,
    "code": "INVALID_REQUEST",
    "message": "The request payload is invalid."
}
```

## Invalid API Credentials

```json theme={null}
{
    "success": false,
    "code": "UNAUTHORIZED",
    "message": "Invalid API credentials."
}
```

## Duplicate Request

```json theme={null}
{
    "success": false,
    "code": "DUPLICATE_REQUEST",
    "message": "A request with this Idempotency-Key has already been processed."
}
```

***

# Best Practices

<Steps>
  <Step title="Generate a unique reference">
    Every payment should have a unique merchant reference.
  </Step>

  <Step title="Use an Idempotency Key">
    Reuse the same Idempotency-Key only when retrying the same request.
  </Step>

  <Step title="Handle Webhooks">
    Always update your payment status using webhook notifications instead of relying only on the synchronous API response.
  </Step>

  <Step title="Store the SplashPay Reference">
    Persist the payment reference returned by SplashPay for reconciliation and support.
  </Step>
</Steps>

***

# Next Steps

* Learn how to check a payment status.
* Configure Webhooks.