☰
Login Register
API Documentation | SpeedPesa

API Documentation

Integrate SpeedPesa payment services into your application with our simple and powerful REST API.

Base URL: https://api.sizahost.com/api

Quick Navigation

Quick Start

  1. Get your API key from the SpeedPesa dashboard
  2. Include x-api-key header in all requests
  3. Send POST requests to the endpoints below
  4. Parse the JSON response in your application
  5. Handle success and error responses appropriately

Authentication

All API requests require authentication using your API key. Include the key in the request header:

x-api-key: YOUR_API_KEY

Note: Keep your API key secure. Never expose it in client-side code.

POST /mobilecashin Pay In (Payment)

Initiate a mobile money payment from customer to merchant. Supports M-Pesa, Airtel Money, Mixx by Yas, and HaloPesa.

Request Headers

HeaderValueRequired
Content-Typeapplication/jsonYes
x-api-keyYOUR_API_KEYYes

Request Body

ParameterTypeDescription
referencestringUnique transaction reference *
utilityrefstringCustomer phone number *
amountstringTransaction amount in TZS *

Example Request

cURL 
curl -X POST https://api.sizahost.com/api/mobilecashin \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "reference": "6997fb4a734bc4.41717538",
    "utilityref": "0748919056",
    "amount": "300"
  }'

Simple Responses

JSON Response (200 OK)
{
  "status": "success",
  "message": "Payment initiated",
  "data": {
    "reference": "6997fb4a734bc4.41717538",
    "transaction_id": "TXN_20250220_001",
    "amount": "300",
    "status": "pending"
  }
}
JSON Response (400 Bad Request)
{
  "status": "error",
  "message": "Invalid phone number",
  "code": "INVALID_PHONE"
}
POST /mobilecashout Payout (Disbursement)

Send money from merchant to customer mobile money wallet. Requires customer PIN for authorization.

Request Headers

HeaderValueRequired
Content-Typeapplication/jsonYes
x-api-keyYOUR_API_KEYYes

Request Body

ParameterTypeDescription
referencestringUnique transaction reference *
utilityrefstringCustomer phone number *
amountstringPayout amount in TZS *
pinstringCustomer authorization PIN *

Example Request

cURL 
curl -X POST https://api.sizahost.com/api/mobilecashout \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "reference": "6997fb4a734d25.97678525",
    "utilityref": "0748919056",
    "amount": "10000",
    "pin": "4852"
  }'

Simple Responses

JSON Response (200 OK)
{
  "status": "success",
  "message": "Payout processed",
  "data": {
    "reference": "6997fb4a734d25.97678525",
    "transaction_id": "TXN_20250220_002",
    "amount": "10000",
    "status": "completed"
  }
}
JSON Response (401 Unauthorized)
{
  "status": "error",
  "message": "Invalid PIN",
  "code": "INVALID_PIN"
}
POST /status Check Transaction Status

Check the current status of any transaction using its reference number.

Request Headers

HeaderValueRequired
Content-Typeapplication/jsonYes
x-api-keyYOUR_API_KEYYes

Request Body

ParameterTypeDescription
referencestringTransaction reference to check *

Example Request

cURL 
curl -X POST https://api.sizahost.com/api/status \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "reference": "64f89ab1c36b5.87654321"
  }'

Simple Responses

JSON Response (200 OK)
{
  "status": "success",
  "data": {
    "reference": "64f89ab1c36b5.87654321",
    "transaction_id": "TXN_20250220_003",
    "amount": "5000",
    "status": "completed",
    "created_at": "2025-02-20 10:30:00",
    "updated_at": "2025-02-20 10:31:15"
  }
}
JSON Response (404 Not Found)
{
  "status": "error",
  "message": "Transaction not found",
  "code": "TXN_NOT_FOUND"
}

Error Codes

CodeMessageDescription
400INVALID_PHONEPhone number format is invalid
400INVALID_AMOUNTAmount is below minimum or above maximum
400INVALID_REFERENCEReference already exists or invalid format
401INVALID_PINCustomer PIN is incorrect
401UNAUTHORIZEDAPI key is missing or invalid
403ACCOUNT_SUSPENDEDAccount has been suspended
404TXN_NOT_FOUNDTransaction reference does not exist
429RATE_LIMITToo many requests, please retry later
500SERVER_ERRORInternal server error, please try again
503SERVICE_UNAVAILABLEService temporarily unavailable

Need API Support?

Our technical team is ready to help with integration questions and troubleshooting.

[email protected]
+255 637 759 997
+255 683 75 997