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

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

cURL
JavaScript
Python
PHP

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"
      }
  }'

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();

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())

$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();

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

{
  "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.

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

Use unique references

Generate a unique payout reference for every disbursement.

Include an Idempotency-Key

Prevent duplicate payouts when retrying requests.

Verify recipients

Use the Name Lookup API before initiating payouts whenever possible.

Listen for webhooks

Use webhook notifications to receive the final transaction status instead of polling.

Getting Started

Collections

Disbursements

Mobile Money

Mobile Money

Endpoint

Authentication

Example Request

Request Body

Example Response

Transaction Status

Verify Recipient

Error Codes

Best Practices

​Mobile Money

​Endpoint

​Authentication

​Example Request

​Request Body

​Example Response

​Transaction Status

​Verify Recipient

​Error Codes

​Best Practices

Mobile Money

Endpoint

Authentication

Example Request

Request Body

Example Response

Transaction Status

Verify Recipient

Error Codes

Best Practices