=== MiCash Payment Gateway for WooCommerce ===
Contributors: unlimitedtech26
Tags: woocommerce, payments, micash
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.2.0.1
License: GPLv2 or later

Release candidate with authenticated MiCash payment status verification.

== Description ==

RELEASE CANDIDATE: Deploy the matching MiCash status endpoint before installing this version. Complete Dev acceptance tests before public release or live payment acceptance.

Version 0.1.1 sends full billing province/state names instead of WooCommerce's stored codes, fixing MiCash's province length validation for provinces such as Gauteng.

This plugin creates MiCash hosted checkouts by calling the existing MiCash360 payment API:

POST /micash/{companyUuid}/payments

The plugin redirects the customer to the returned hosted checkout URL. Settlement, provider callbacks, and WebPay payment notifications remain owned by MiCash360.

== Setup ==

1. Install and activate WooCommerce.
2. Install and activate this plugin.
3. Go to WooCommerce > Settings > Payments > MiCash.
4. Configure the MiCash API base URL, company UUID, integrator secret, and optional payer account UUID.
5. Enable MiCash.

Use classic checkout with [woocommerce_checkout]. Checkout Block support is not implemented.

Test mode selects the test API address; it does not simulate payments. Use a separate sandbox merchant and sandbox credentials.

== Installation ==

1. In WordPress, choose Plugins > Add New > Upload Plugin and select micash-payment-gateway.zip.
2. Install and activate it with WooCommerce active. For an upgrade, choose Replace current with uploaded.
3. Open WooCommerce > Settings > Payments > MiCash. Enable the gateway and Test mode.
4. Enter your reachable sandbox base URL, merchant Company UUID, and matching sandbox API key. Leave the live URL blank.
5. Edit the Checkout page to use a Shortcode block containing [woocommerce_checkout]. Select this page under WooCommerce > Settings > Advanced.
6. Create a simple virtual test product, set the store currency to the sandbox merchant's currency, then try checkout with test data.

== External service and data ==

This plugin requires an existing MiCash sandbox merchant account and API credentials. When the customer places an order with MiCash, WordPress sends the order reference, product descriptions and amounts, billing address, customer name, email, phone number, and return URLs to the MiCash API base URL configured by the store administrator. The API key authenticates that request. The browser then opens the returned hosted checkout URL.

Use synthetic customer data for this beta. Obtain service terms and privacy information from your MiCash account provider before onboarding other users. Do not enter credentials for a server you do not trust.

== Changelog ==

= 0.1.1 =
Maps stored province codes to full province names. Packaged as a sandbox beta with installation instructions and explicit limitations.

== Testing guide ==

See wordpress/README.md in the repository for a browser-based WordPress Playground link, plugin upload instructions, sample product setup, settings, and troubleshooting. See wordpress/test-site/README.md for Docker setup.

== Current limitations ==

Version 0.2.0.1 checks payment status through the authenticated MiCash API on browser return and through scheduled background checks. Payment completion requires matching payment reference, merchant, order reference, amount and ZAR currency. Browser return parameters cannot mark an order paid, failed or cancelled. Previously paid/refunded orders are protected from delayed updates. WP-Cron must run reliably on a persistent WordPress host; Playground is not suitable for validating background processing while closed.

Old 0.1.x orders do not contain verification metadata and require manual reconciliation. Use new orders to test this release. Refunds, subscriptions, additional WooCommerce fees and Checkout Block integration are not supported. Tests of real callback processing on Dev remain required.

New checkout logs record HTTP codes without response bodies. Delete or restrict old logs that may contain tokens. Disable debugging after testing.
