WP Manifestindependent plugin directory
manifest / ecommerce / kcb-mpesa-express-wordpress-plugin

KCB M-Pesa STK Push Gateway

Custom WooCommerce payment gateway for KCB M-Pesa STK Push API.

by Stevehoober · github.com/stevehoober254/kcb-mpesa-express-wordpress-plugin

★ 1stars

Install

Download source zip No release zip yet

This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.

Install straight from GitHub with WP-CLI:

wp plugin install https://github.com/stevehoober254/kcb-mpesa-express-wordpress-plugin/archive/refs/heads/main.zip
No built-in updater. New versions won't appear under Dashboard → Updates. Install new releases yourself, or let Git Updater track the repository.
Readme github.com/stevehoober254/kcb-mpesa-express-wordpress-plugin ↗

💳 KCB M-Pesa Express WooCommerce Gateway

A production WordPress plugin enabling KCB M-Pesa STK Push payments in WooCommerce stores across Kenya and East Africa. Free core + Pro tier with extended features.

Why this exists: KCB's M-Pesa Express API is widely used in Kenya but has no official WooCommerce integration. This plugin fills that gap with a clean, extensible implementation.

Features

Free

  • ✅ Full STK Push payment flow at WooCommerce checkout
  • ✅ Secure OAuth2 token generation with KCB API
  • ✅ Real-time callback handling → automatic order status updates
  • ✅ Admin callback log dashboard (view, download, clear)
  • ✅ Email alerts on payment failures

Pro

  • 🔐 License key activation system
  • 📊 CSV export of payment logs
  • 📣 Slack / Telegram payment notifications (planned)
  • 🎨 Advanced checkout UI customisation

Architecture

kcb-mpesa-gateway/
├── admin/
│   └── logs-ui.php              # Admin log dashboard
├── includes/
│   ├── class-gateway-base.php   # Abstract base — extensible for other M-Pesa providers
│   ├── class-gateway-free.php   # Free tier implementation
│   └── class-gateway-pro.php    # Pro tier with licence check
├── pro/
│   └── class-license-manager.php
├── kcb-mpesa-gateway.php        # Plugin entry point
└── init_kcb-mpesa-gateway.php   # Gateway registration + callback endpoint

Design decisions:

  • Abstract base class (class-gateway-base.php) makes it straightforward to extend for other KCB payment products or M-Pesa providers
  • Callbacks are logged to a flat file (wp-content/mpesa-callback-log.txt) — avoids DB write overhead during high-volume payment events
  • Token generation is handled per-request with short TTL — avoids stale token issues that plague many community implementations

Installation

  1. Upload to /wp-content/plugins/kcb-mpesa-gateway
  2. Activate via Plugins in WordPress admin
  3. Go to WooCommerce → Settings → Payments → enable KCB M-Pesa
  4. Enter your Consumer Key and Consumer Secret from KCB Developer Portal
  5. For Pro: enter your licence key at WooCommerce → Settings → KCB M-Pesa Licence

Sandbox testing

Use KCB's sandbox environment at https://sandbox.buni.kcbgroup.com with test credentials from the portal. The plugin switches between sandbox and production endpoints based on WooCommerce's test mode toggle.

Roadmap

  • [ ] Publish to WordPress.org plugin directory
  • [ ] Add support for Safaricom M-Pesa Daraja API (alternative gateway class)
  • [ ] Webhook signature verification
  • [ ] Unit tests with WP_Mock

📌 Part of my fullstack portfolio demonstrating real-world payment integrations for African e-commerce.

📧 stephengachoka57@gmail.com | 🌐 stephengachoka.co.ke | 📍 Nairobi, Kenya