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

```text theme={null}
https://api.splashpay.co.tz/api/v1
```

***

# 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

```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);
}
```

***

## 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": {
    "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",
    "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.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.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.

***

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

> [!NOTE]
>
> Always verify the webhook signature before processing the payload and return an HTTP **200 OK** response after successful processing to prevent unnecessary retries.

***

# 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

**1. Generate a unique reference**

Every payment should have a unique merchant reference.

**2. Use an Idempotency Key**

Reuse the same Idempotency-Key only when retrying the same request.

**3. Handle Webhooks**

Always update your payment status using webhook notifications instead of relying only on the synchronous API response.

**4. Store the SplashPay Reference**

Persist the payment reference returned by SplashPay for reconciliation and support.

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.