=== AlkaPay Payment Gateway with M-Pesa for WooCommerce ===
Contributors: alkapay
Tags: mpesa, payment-gateway, mobile-money, kenya, woocommerce
Requires at least: 6.0
Tested up to: 7.0
Stable tag: 1.2.4
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
WC requires at least: 6.0
WC tested up to: 9.9.3

Accept M-Pesa payments in WooCommerce — show your Paybill or Till at checkout, collect transaction codes, and verify orders. Pro adds STK Push.

== Description ==

**AlkaPay** is a complete M-Pesa payment gateway for WooCommerce that enables Kenyan merchants to accept mobile money payments from their customers through Safaricom's M-Pesa.

The **free version** gives you a fully functional manual M-Pesa payment gateway — your Paybill or Buy Goods (Till) number is displayed at checkout, customers pay directly from their phone, enter the M-Pesa transaction code to confirm, and you verify the payment to complete the order.

The **Pro version** supercharges your store with automated STK Push — the payment prompt is sent directly to the customer's phone at checkout, and the order is automatically completed the moment they enter their M-Pesa PIN. No manual steps required.

= Free Version Features =

* **Manual M-Pesa Payments** — Display your Paybill or Buy Goods (Till) number on the WooCommerce checkout page
* **Transaction Code Collection** — Customers enter their M-Pesa transaction code after paying to confirm the order
* **Manual Payment Verification** — Verify M-Pesa payments from your WooCommerce admin and complete orders
* **Paybill & Buy Goods Support** — Works with both Safaricom Paybill numbers and Buy Goods (Till) numbers
* **Configurable Order Status** — Choose which status an order takes while a manual payment is awaiting your verification
* **Beautiful Admin Dashboard** — Modern admin interface to manage your M-Pesa payment settings
* **Order Management** — View M-Pesa transaction details directly on the WooCommerce order page
* **Automatic Updates** — Stay up to date with the latest features and security patches

= Pro Version Features =

* **Automated STK Push** — Send the M-Pesa payment prompt directly to the customer's phone at checkout. No more typing Paybill numbers!
* **Automatic Order Completion** — Orders are automatically marked as "Processing" the instant the customer pays via STK Push. Zero manual intervention
* **Advanced Analytics Dashboard** — Visual charts and reports showing your M-Pesa revenue, transaction trends, and payment success rates
* **Comprehensive Transaction Logging** — Detailed logs of every API call, callback, and transaction for troubleshooting and auditing
* **Manual Payment Verification (Pro)** — Enhanced payment lookup using M-Pesa transaction codes with automatic order matching
* **Priority Support** — Get help directly from the AlkaPay team

= Why AlkaPay? =

* **Built for Kenya** — Purpose-built for the Kenyan market and Safaricom's M-Pesa ecosystem
* **WooCommerce Native** — Integrates seamlessly as a WooCommerce payment gateway with full order lifecycle support
* **Secure by Design** — All API credentials are encrypted, all database queries are prepared against SQL injection, and all outputs are properly escaped
* **Lightweight** — No bloat, no unnecessary dependencies. Just a clean, fast payment gateway
* **Freemius Licensed** — Industry-standard licensing with secure updates and account management

= Disclaimer =

AlkaPay is an independent, third-party product and is **not affiliated with, endorsed by, or sponsored by Safaricom PLC or WooCommerce/Automattic**. "M-Pesa", "Safaricom", and "Daraja" are trademarks of Safaricom PLC, and "WooCommerce" is a trademark of Automattic Inc. These names are used here only to describe the plugin's compatibility and functionality. To use M-Pesa STK Push you must obtain your own credentials directly from Safaricom's Daraja portal.

= Requirements =

* WordPress 6.0 or higher
* WooCommerce 6.0 or higher
* PHP 7.4 or higher
* A Safaricom Paybill or Buy Goods (Till) number
* M-Pesa API credentials from the [Safaricom Daraja Portal](https://developer.safaricom.co.ke/) (required for Pro STK Push)

== External services ==

This plugin connects to the following third-party services. No data is ever sent until you actively configure and use the relevant feature.

= Safaricom M-Pesa (Daraja) API =

What it is and why it's used: AlkaPay is an M-Pesa payment gateway. To process payments it communicates with Safaricom's official M-Pesa Daraja API — to authenticate (OAuth), send STK Push prompts, query payment status, and receive payment confirmation callbacks.

When data is sent: when you click "Test Connection", when a customer pays with M-Pesa at checkout, when the plugin queries a pending payment's status, and when Safaricom sends a payment confirmation to your callback URL.

What data is sent: your M-Pesa API credentials (Consumer Key, Consumer Secret, Passkey) for authentication; the business short code / Till number; the customer's phone number; the payment amount; and an order reference. Data is sent over HTTPS to `https://sandbox.safaricom.co.ke` (test mode) or `https://api.safaricom.co.ke` (live mode).

This service is provided by Safaricom PLC. Its use is subject to:
* Daraja API documentation: https://developer.safaricom.co.ke/
* Daraja API terms and conditions, and privacy policy: https://developer.safaricom.co.ke/terms

= Freemius (licensing & updates) =

What it is and why it's used: AlkaPay uses Freemius to deliver software updates, manage Pro licenses, and (optionally) collect anonymous usage diagnostics to improve the plugin.

When data is sent: on activation you are asked to opt in. If you decline, no data is sent. License-related calls are made only when you activate, deactivate, or sync a license. Update checks are made periodically by WordPress.

What data is sent (only with your consent): site URL, WordPress and PHP versions, active theme/plugin list, and your administrator email for license correspondence. AlkaPay does NOT send your customers' data, orders, or M-Pesa transactions to Freemius.

This service is provided by Freemius, Inc. Its use is subject to:
* Freemius terms of service: https://freemius.com/terms/
* Freemius privacy policy: https://freemius.com/privacy/

Bundled library and its source: this plugin bundles the Freemius WordPress SDK v2.13.4 in
`vendor/freemius/`, licensed GPL-3.0-only (see `vendor/freemius/LICENSE.txt`), which is compatible
with this plugin's GPLv2-or-later licence. Some of the SDK's own CSS and JavaScript assets ship
pre-built rather than as readable source. The complete, unminified source for the bundled version is
published at:
* https://github.com/Freemius/wordpress-sdk (tag 2.13.4)

No other third-party libraries are bundled, and none of AlkaPay's own CSS or JavaScript is minified —
every file under `assets/` is human-readable source.

== Installation ==

= Automatic Installation =

1. Go to your WordPress admin dashboard
2. Navigate to **Plugins > Add New**
3. Search for "AlkaPay" or upload the plugin ZIP file
4. Click **Install Now**, then **Activate**
5. Go to **M-PESA Gateway > Settings** to configure your payment details

= Manual Installation =

1. Download the plugin ZIP file
2. Upload the `alkapay` folder to `/wp-content/plugins/` on your server
3. Activate the plugin through the **Plugins** menu in WordPress
4. Go to **M-PESA Gateway > Settings** to configure your Paybill or Buy Goods number

= Quick Start (Free Version) =

1. Go to **M-PESA Gateway > Settings**
2. Select your Transaction Type: **Paybill** or **Buy Goods (Till)**
3. Enter your Paybill/Till number and Account Reference
4. Save your settings — your checkout page will now display M-Pesa payment instructions
5. When a customer places an order and enters their M-Pesa transaction code, go to the order in WooCommerce to verify and complete it

= Quick Start (Pro Version) =

1. Activate your Pro license on the **M-PESA Gateway > Account** page
2. Go to **M-PESA Gateway > Settings**
3. Enter your Safaricom Daraja API credentials (Consumer Key, Consumer Secret, Passkey)
4. Choose **Sandbox** to test, or **Production** when you are ready to take live payments
5. Save — your checkout will now send automated STK Push prompts to customers' phones!

== Frequently Asked Questions ==

= What does the free version do? =

The free version displays your M-Pesa Paybill or Buy Goods (Till) number on the WooCommerce checkout page. Customers pay you directly via M-Pesa, then enter their transaction code on the order confirmation page. You can then verify the payment and complete the order from your WordPress admin.

= What does the Pro version add? =

Pro adds automated STK Push — the M-Pesa payment prompt appears directly on the customer's phone during checkout. Once they enter their PIN, the order is automatically completed without any manual intervention. Pro also includes an analytics dashboard, detailed transaction logging, and enhanced manual payment verification.

= Do I need M-Pesa API credentials? =

**For the free version:** No. You only need your Paybill or Buy Goods (Till) number.
**For the Pro version:** Yes. You need to register on the [Safaricom Daraja Developer Portal](https://developer.safaricom.co.ke/) and create an app to get your Consumer Key, Consumer Secret, and Passkey for live STK Push.

= Can I try STK Push before buying Pro? =

Yes — try it on our live demo store at [demo.alkapay.co.ke](https://demo.alkapay.co.ke), which runs the Pro version so you can see the whole STK Push checkout without installing anything.

= What payment methods are supported? =

* **Free:** Manual payments via Paybill and Buy Goods (Till) with transaction code verification
* **Pro:** Automated STK Push via Paybill and Buy Goods, plus enhanced manual payment verification

= Is this plugin secure? =

Yes. AlkaPay follows WordPress security best practices including prepared database queries, input sanitization, output escaping, and nonce verification. API credentials are stored securely in the WordPress database.

= How do I get Pro features? =

Visit the **M-PESA Gateway > Account** page in your WordPress admin and click "Upgrade". You can also purchase a license at [alkapay.co.ke](https://www.alkapay.co.ke).

== Screenshots ==

1. M-Pesa payment page — pay via Paybill or Buy Goods (Till) and enter your transaction code
2. Admin dashboard with M-Pesa payment activity
3. Order details showing M-Pesa transaction information
4. Pro analytics dashboard with revenue charts

== Changelog ==

= 1.2.4 =
* Fixed: AlkaPay could crash your site if another M-Pesa plugin was active at the same time. It now runs safely alongside other plugins.

= 1.2.3 =
* Security: The M-Pesa payment page now confirms you own an order before it shows any order details, so order information can no longer be viewed by guessing an order number in the address bar.
* Security: The secret in your M-Pesa callback URL is now generated in a more secure way. Your callback URL does not change, so there is nothing to re-register.
* Changed: AlkaPay's internal names are now unique to AlkaPay, so it will not clash with other plugins. Your settings and saved payments carry over automatically — there is nothing to do.
* Fixed: The "rate AlkaPay" links now open all reviews on WordPress.org rather than a pre-filled star rating.
* Maintenance: Behind-the-scenes code quality improvements.

For the changelog of earlier releases, see changelog.txt in the plugin folder.

== Upgrade Notice ==

= 1.2.4 =
Fixes a crash that could occur when another M-Pesa plugin is active at the same time. Recommended for all users.

= 1.2.3 =
Security and privacy improvements — the payment page now checks you own an order before showing it, and AlkaPay's internal names are now unique so it will not clash with other plugins. Your settings carry over automatically. Recommended for all users.

