API Documentation

Seamless M-Pesa integration for modern businesses. All responses are JSON formatted.

Authentication

Every request must include your secret_key, passkey, and shortcode — found in your dashboard.

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

All requests are encrypted via TLS 1.2+

Initiate STK Push

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

Parameters

Parameter	Type	Required	Description
secret_key	string	Yes	Account secret key
passkey	string	Yes	20-character passkey
shortcode	string	Yes	7-digit Till/Paybill
amount	number	Yes	KES amount (min 1)
phone	string	Yes	2547XXXXXXXX or 07XXXXXXXX
reference	string	No	Required for Paybill

Example

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

Response

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

Save the transaction_id for status checks.

Transaction Status

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

Parameters

Parameter	Type	Required	Description
secret_key	string	Yes	Account secret key
passkey	string	Yes	Account passkey
shortcode	string	Yes	7-digit shortcode
transaction_id	string	Yes	From initiatestk response

Response

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

Webhooks

Liparo sends a POST request to your webhook URL when a transaction completes. Respond with HTTP 200 OK within 5 seconds.

Payload

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

Configure webhooks in your dashboard. Idempotency keys recommended.

Error Codes

Code	Error	Description
400	Bad Request	Missing parameters or invalid format
401	Unauthorized	Invalid credentials
404	Not Found	Transaction not found
405	Method Not Allowed	HTTP method not supported
429	Too Many Requests	Rate limit exceeded
500	Internal Error	Server error — retry later

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

Rate Limits

100 requests per minute per account. Exceed the limit and receive a 429 response.

Monitor usage via the dashboard.

Support

Need help? We're here for you.

Email: support@liparo.co.ke

Hours: 24/7 — We respond within 1 hour