REST API V1.0

Cyzora API Documentation

Integrate M-Pesa STK Push checkouts, verify incoming Paybill payments, and disburse B2C transfers using standard HTTPS REST endpoints and signed HMAC webhooks.

1. Quickstart

Send your first test charge in under 3 minutes.

Step 1: Get Secret Key

Step 2: Send POST Request

Dispatch a JSON charge object containing customer phone and amount.

Step 3: Receive Webhook

Listen for the verified HMAC callback once customer enters PIN.

cURL Example Charge

curl -X POST "https://api.cyzora.co.ke/v1/charges" \
  -H "Authorization: Bearer sec_key_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500,
    "phone": "254712345678",
    "reference": "INV-2026-084",
    "callback_url": "https://api.yourdomain.com/webhooks/cyzora"
  }'

2. Authentication

All API requests must include your secret API key in the HTTP Authorization header.

Authorization: Bearer sec_key_live_yourSecretKeyGoesHere

Always keep your live secret keys secure. Never expose secret keys in client-side code, mobile binaries, or public GitHub repositories.

3. Charges (STK Push)

Triggers an instantaneous Safaricom M-Pesa STK push PIN prompt.

POSThttps://api.cyzora.co.ke/v1/charges

Field	Type	Required	Description
amount	Integer	Yes	Transaction amount in Kenyan Shillings (KES). Min 1, Max 300,000.
phone	String	Yes	Customer Safaricom phone in MSISDN format, e.g. `254712345678`.
reference	String	Yes	Your internal order, invoice, or user account identifier (Max 32 chars).
callback_url	String	Optional	HTTPS endpoint to receive the charge webhook event notification.

4. Webhooks & HMAC Verification

Cyzora sends signed webhook notifications when payments complete or fail.

Sample Webhook Payload: charge.succeeded

{
  "event": "charge.succeeded",
  "id": "evt_99018241",
  "created_at": 1756641600,
  "data": {
    "charge_id": "chg_99201928",
    "amount": 1500,
    "currency": "KES",
    "phone": "254712345678",
    "reference": "INV-2026-084",
    "mpesa_receipt": "TBR89X1024",
    "status": "success",
    "completed_at": "2026-08-31T11:58:00+03:00"
  }
}

Verifying the Webhook Signature

Each incoming webhook request includes an X-Cyzora-Signature header containing an HMAC-SHA256 hash of the raw JSON body signed with your secret webhook key.

5. Brevo SMTP Integration

Deliver transactional receipts and notifications over Brevo SMTP relay.

SMTP Host Server

smtp-relay.brevo.com

SMTP Port

587 (STARTTLS)

Username

Your Brevo Login Email

Master SMTP Key

xsmtpsib-...

6. SDKs & Packages

Maintained client libraries for backend development.

Node.js / TypeScript

npm install @cyzora/pay

Python 3

pip install cyzora-pay

PHP / Composer

composer require cyzora/cyzora-pay

Go (Golang)

go get github.com/cyzorapay/cyzora-go