Universal M-Pesa Client
Version: 1.3.1

WORDPRESS PLUGIN INFORMATION
- Requires WordPress 6.0 or later.
- Requires PHP 7.4 or later.
- WooCommerce is optional. Standalone checkout and API application form work without WooCommerce.
- The Client connects to the Central platform over HTTPS.

MERCHANT API APPLICATION — WORDPRESS ADMIN
1. Install and activate Universal M-Pesa Client.
2. Open Universal M-Pesa > Connection Settings.
3. Enter the HTTPS URL of the primary Universal M-Pesa Central website and save. Leave the API key blank while applying.
4. Open Universal M-Pesa > Apply for API Key.
5. The form is prefilled with the WordPress site name, current administrator's display name and email, and this website's URL. Complete the phone number and review all details.
6. Submit the application. The Client sends the application to the Central REST endpoint over HTTPS.
7. The Central administrator receives an email notification and reviews it under Universal M-Pesa > Applications.
8. On approval, Central creates or links a merchant WordPress account, issues a site-specific API key, stores only its SHA-256 hash and emails the raw key once to the applicant.
9. Return to Universal M-Pesa > Connection Settings, enter the issued key and save the connection.

OPTIONAL PUBLIC APPLICATION FORM
The [universal_mpesa_api_application] shortcode remains available for sites that prefer a public application page. It is no longer required for the normal merchant application workflow.

WOOCOMMERCE PAYMENT EXPERIENCE — NEW IN 1.1.3
- After checkout starts the STK Push, the customer is redirected to the normal WooCommerce order-received page.
- The Client adds an M-Pesa payment confirmation panel to that page for orders paid with this gateway.
- The panel instructs the customer to approve the STK prompt and automatically polls the configured Central platform every five seconds (up to ten minutes).
- Poll requests verify the WooCommerce order key and a per-order WordPress nonce before querying Central.
- Returned Central payment ID, amount and currency are checked against the order before the existing signed webhook processing logic is invoked.
- When paid, the order is completed through WooCommerce payment_complete() via the existing webhook handler, the receipt is displayed, and the Thank You page reloads to show the updated order state.
- Failed, rejected, cancelled, timed-out and review-required statuses are shown to the customer. The customer is advised not to pay again until the status is verified.
- The signed Central-to-merchant webhook remains enabled and is still the primary asynchronous confirmation path. Polling provides a fallback if the webhook is delayed or missed.
- Already-paid orders show a confirmation and receipt without starting polling. Existing pending requests are reused rather than starting another STK Push.

SECURITY / OPERATIONS
- Application submissions require HTTPS Central and HTTPS merchant website URLs.
- The Central platform applies an IP-based submission cooldown and duplicate pending-application check.
- Admin application submission is restricted to users with manage_options and protected by a WordPress admin nonce.
- The optional public form uses a WordPress nonce and honeypot field.
- API keys are not displayed in Client settings. Leave the API key field blank to retain an already saved key; enter a new key only to replace it.
- Central administrator approval is required before API keys are issued.
- Configure reliable WordPress email delivery (SMTP recommended) on Central so application notices and issued credentials can be delivered.

EXISTING SHORTCODES
[universal_mpesa_checkout]
Optional: [universal_mpesa_checkout amount="250" reference="Invoice 123" button="Pay now"]
[universal_mpesa_payment_status]
[universal_mpesa_api_application]
[universal_mpesa_dashboard] remains a Central-side shortcode.

WOOCOMMERCE
- Registers a real WC_Payment_Gateway when WooCommerce is active.
- Registers a Checkout Blocks payment method when the WooCommerce Blocks integration API is available.
- Declares HPOS compatibility and uses wc_get_order()/WC_Order metadata APIs.
- Merchant API key and Central URL are configured under Universal M-Pesa > Connection Settings.
- Gateway currently accepts KES orders with whole-shilling totals only.

LIMITATIONS / TESTING
- PHP syntax checks and ZIP integrity checks are performed for this build.
- This environment does not have the merchant's live WordPress/WooCommerce installation or Safaricom Daraja credentials, so the new Thank You page polling, actual Central status response, webhook delivery, Checkout Blocks, HPOS and end-to-end payment flow have not been runtime-tested here.
- Test first with a low-value Sandbox/staging order. Confirm the STK prompt appears, keep the Thank You page open, and verify that a paid callback or successful Central status poll updates the order once and displays the receipt.
- Confirm that failed/cancelled transactions do not mark orders paid and that a repeat page visit does not start a second STK Push.

CHANGELOG
1.1.3
- Adds a customer-facing M-Pesa waiting/confirmation panel to the WooCommerce Thank You page.
- Adds secure order-key/nonce protected status polling against Central every five seconds for up to ten minutes.
- Validates Central payment ID, amount and currency before applying polled status through the existing signed webhook handler.
- Displays confirmed receipt or terminal payment status and refreshes the Thank You page after confirmation.
- Retains existing payment gateway, Checkout Blocks integration, standalone shortcodes and API application workflow.

1.1.2
- Added a native WordPress admin application screen at Settings > Apply for API Key.
- Prefills business name, current administrator contact name/email and website URL.
- Sends applications to the configured Central platform and displays success/error feedback in wp-admin.
- Retains the public application shortcode for optional use.
- Updates connection settings page instructions to link directly to the admin application screen.


Version 1.2.0
- Adds Settings > My M-Pesa Wallet for authenticated merchants.
- Wallet balance, collections, payment activity and withdrawal history are retrieved live from Central using the saved server-side API key.
- Withdrawal requests are submitted to Central; Central remains authoritative for fee calculation, balance checks, reservation and approval.
- Adds an Open My M-Pesa Wallet shortcut to the connection settings page.
- Requires Universal M-Pesa Central v1.3.0 or later with the merchant wallet API routes.


Version 1.3.0
- Moves all Client administration pages out of WordPress Settings into a dedicated top-level Universal M-Pesa menu.
- Makes My M-Pesa Wallet the top-level landing page for faster merchant access.
- Adds Connection Settings and Apply for API Key as dedicated submenu pages.
- Updates internal navigation links and setup instructions.
- Preserves existing settings option, API key, wallet API calls, gateway, checkout, webhook and application workflows.


Version 1.3.1
- Retains the dedicated top-level Universal M-Pesa administration menu.
- Removes the legacy Settings-page redirect; old URLs are left to WordPress without forced navigation.
- Moves the M-Pesa confirmation panel to the beginning of the WooCommerce order-received page using the before-thankyou hook.
- Retains the v1.2.0 payment gateway, STK request, status polling, webhook verification, order confirmation and Blocks integration code.
