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

POST /payments/mobile-money

Base URLs

Sandbox
Production

https://sandbox-api.splashpay.co.tz/api/v1

Use this environment for development and testing.

https://api.splashpay.co.tz/api/v1

Use this environment for live transactions.

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

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

Successful Response

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

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

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.

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

Webhook notifications may be delivered more than once. Your webhook endpoint should be idempotent by checking the payment reference before processing the event.

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

{
    "success": false,
    "code": "INVALID_REQUEST",
    "message": "The request payload is invalid."
}

Invalid API Credentials

{
    "success": false,
    "code": "UNAUTHORIZED",
    "message": "Invalid API credentials."
}

Duplicate Request

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

Best Practices

Generate a unique reference

Every payment should have a unique merchant reference.

Use an Idempotency Key

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

Handle Webhooks

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

Store the SplashPay Reference

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

Next Steps

Learn how to check a payment status.
Configure Webhooks.

​Mobile Money

​Endpoint

​Base URLs

​Request Body

​Example Request

​Successful Response

​Response Fields

​Payment Status

​Sample Webhook Payload

​Webhook Fields

​Supported Events

​Error Responses

​Invalid Request

​Invalid API Credentials

​Duplicate Request

​Best Practices

​Next Steps

Mobile Money

Endpoint

Base URLs

Request Body

Example Request

Successful Response

Response Fields

Payment Status

Sample Webhook Payload

Webhook Fields

Supported Events

Error Responses

Invalid Request

Invalid API Credentials

Duplicate Request

Best Practices

Next Steps