Developer Reference

Welcome to the Cyzora integration guide. Get started with direct curl commands, learn webhook payload objects, and query live parameters using our language SDK libraries.

Quickstart

Accept M-Pesa payments by following three easy steps:

1 Sign up

2 Link Secrets

Copy your live secret key from the settings console panel under the developers tab.

3 Send Charge

Perform a POST request containing the target amount and phone. M-Pesa prompts PIN entry immediately.

Test cURL Charge

curl -X POST "https://api.cyzora.co.ke/v1/charges" \
  -H "Authorization: Bearer sec_key_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "phone": "254700000000",
    "reference": "DEMO-PAY",
    "description": "API Test Charge",
    "callback_url": "https://yourserver.com/callback"
  }'

Authentication

Cyzora uses HTTP Bearer tokens to validate backend actions. Pass your key securely inside standard HTTP Authorization headers. Keep keys safe: never commit keys to repositories or expose them clientside.

Authorization: Bearer sec_key_live_yourSecretKeyGoesHere

Charges (STK Push)

Create a payment attempt by calling the charges endpoint. Cyzora routes an STK push alert to the client's Safaricom SIM automatically.

Endpoint:

POST https://api.cyzora.co.ke/v1/charges

Field	Type	Required	Description
amount	Integer	Yes	The transaction amount in Kenyan Shillings (KES).
phone	String	Yes	Payer phone starting with prefix, e.g. `254712345678`.
reference	String	Yes	Your identifier (order/billing code). Max 20 characters.
description	String	No	Optional note regarding this specific transaction.
callback_url	String	No	Webhook destination where the finalized event is sent.

Webhooks

Webhooks let you monitor transaction changes asynchronously. Since prompt authorization is dependent on human validation speed, rely on webhook events to confirm client payments.

Webhook JSON: `charge.succeeded`

This transaction payload is pushed to your callback url upon successful PIN authorization:

{
  "id": "evt_9X82J1K9S8A",
  "type": "charge.succeeded",
  "created_at": 1719224400,
  "data": {
    "charge_id": "chg_a8s9d8a9asd",
    "amount": 100,
    "phone": "254700000000",
    "reference": "DEMO-PAY",
    "mpesa_receipt": "QA982J1K9S",
    "status": "success",
    "completed_at": "2026-06-24T12:35:00+03:00"
  }
}

Payouts

Transfer funds from your merchant ledger back to M-Pesa via our Payout API endpoints or dashboard actions.

🔒 Security Notice: Automated API payouts require configuring an IP whitelist inside the developer settings dashboard tab before requests will succeed.

SDKs & Libraries

Speed up implementation using our officially supported language packages:

Node.js SDK

npm install @cyzora/node

Python SDK

pip install cyzora-sdk

PHP Library

composer require cyzora/php