📘 API Documentation

Welcome to Liparo API — the seamless M-Pesa gateway. Integrate payments quickly, check transaction status, and handle webhooks with ease. All responses are JSON formatted.

🔑 Authentication

Every request must include your credentials. After linking a Till or Paybill, you'll find your secret_key, passkey and shortcode in your dashboard. Keep them safe!

{
  "secret_key": "sk_live_abc123xyz",
  "passkey": "b9f2c8a7d3e1f4h5j6k7",
  "shortcode": "1234567"
}

All communications are encrypted via TLS 1.2+

📲 Initiate STK Push

POST https://api.liparo.co.ke/v1/initiatestk

📋 Request Parameters

Parameter	Type	Required	Description
secret_key	string	Yes	Your account secret key
passkey	string	Yes	20-character passkey
shortcode	string	Yes	7-digit M-Pesa shortcode (Till/Paybill)
amount	number	Yes	Amount in KES (min 1)
phone	string	Yes	Customer phone (2547XXXXXXXX or 07XXXXXXXX)
reference	string	No	Transaction reference (required for Paybill)

📤 Example Request (cURL)

curl -X POST https://api.liparo.co.ke/v1/initiatestk \
  -H "Content-Type: application/json" \
  -d '{
    "secret_key": "abc123def456",
    "passkey": "xyz789passkey123",
    "shortcode": "1234567",
    "amount": 100,
    "phone": "254712345678",
    "reference": "INV001"
  }'

✅ Success Response

{
  "success": true,
  "transaction_id": "LIP202401011200001234",
  "message": "STK Push initiated successfully",
  "merchant_request_id": "12345-67890",
  "checkout_request_id": "ws_CO_123456789"
}

The transaction_id should be stored for later status checks.

🔍 Check Transaction Status

POST https://api.liparo.co.ke/v1/checktransaction

📋 Request Parameters

Parameter	Type	Required	Description
secret_key	string	Yes	Your account secret key
passkey	string	Yes	Your account passkey
shortcode	string	Yes	Your 7-digit shortcode
transaction_id	string	Yes	Transaction ID from initiatestk response

📤 Sample Response

{
  "success": true,
  "transaction_id": "LIP202401011200001234",
  "status": "Completed",
  "amount": 100,
  "phone": "254712345678",
  "reference": "INV001",
  "mpesa_receipt": "MPESA123456789",
  "result_desc": "Payment successful",
  "created_at": "2024-01-01 12:00:00"
}

🔄 Webhooks

After a transaction completes, Liparo sends a POST request to your configured webhook URL. Ensure your endpoint responds with HTTP 200 OK within 5 seconds.

📦 Webhook Payload Structure

{
  "transaction_id": "LIP202401011200001234",
  "status": "Completed",
  "amount": 100,
  "phone": "254712345678",
  "reference": "INV001",
  "mpesa_receipt": "MPESA987654321",
  "result_desc": "Payment successful"
}

You can set up webhook endpoints in your developer dashboard. Idempotency keys are recommended for duplicate prevention.

⚠️ Error Codes & Responses

All API errors follow standard HTTP status codes with a JSON error body:

HTTP Code	Error Type	Description
400	Bad Request	Missing required parameters or invalid format (e.g., amount < 1)
401	Unauthorized	Invalid secret_key / passkey pair
404	Not Found	Transaction ID not found or expired
405	Method Not Allowed	HTTP method not supported for the endpoint
429	Too Many Requests	Rate limit exceeded (100 req/min)
500	Internal Server Error	Something went wrong on Liparo's side — retry later

{
  "success": false,
  "error_code": 401,
  "message": "Invalid credentials: secret_key mismatch"
}

⏱️ Rate Limits & Fair Usage

Each API account is limited to 100 requests per minute. Burst tolerance is allowed up to 120 requests. If you exceed the limit, you'll receive a 429 Too Many Requests response. For higher volume needs, please contact our sales team.

Monitor your usage via the dashboard analytics section.