=== MiCash Payments ===
Contributors: unlimitedtech26
Tags: payments, micash
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Standalone fixed-amount MiCash payments with separate Sandbox and Production environments, without WooCommerce.

== Description ==

MiCash Payments connects a WordPress payment page to MiCash360 hosted checkout without requiring an ecommerce plugin. Set a fixed amount in South African rand (ZAR), add the [micash_payment] shortcode to a page, and let customers enter their billing and contact details before continuing to MiCash.

The plugin supports two explicit environments. Sandbox uses https://dev.micash360.co.za and Production uses https://process.micash360.co.za. The endpoints are fixed in the plugin and are not editable by administrators. Sandbox and Production Company UUID/API key credentials are stored separately, so changing environments does not overwrite the other environment's credentials.

View recent payment references, environments and statuses in your WordPress dashboard and request an authenticated status check. Payment confirmation checks the merchant, reference, amount and currency against the MiCash API; a browser redirect alone never confirms payment. A MiCash merchant account and the appropriate environment credentials are required. Payment methods and service charges are determined by your MiCash service agreement.

Features:

* Explicit Sandbox/Test and Production/Live environment selection.
* Separate merchant credentials for Sandbox and Production.
* Fixed, non-editable MiCash API origins for each environment.
* One administrator-configured payment amount and description per site.
* A shortcode payment form with South African billing details.
* Hosted checkout, with no card details collected by this plugin.
* Private payment records tagged with their environment.
* Manual status checks and scheduled authenticated verification.
* Existing payment verification continues against the environment in which that payment was created.
* No WooCommerce installation, product catalogue or cart required.

Add [micash_payment] to a Shortcode block. The site administrator sets one payment description and fixed ZAR amount for the site. Customers enter billing details and continue to MiCash hosted checkout. No products, cart, shipping or WooCommerce orders are created. Payment records appear in the MiCash Payments admin menu.

No browser success parameter can mark a payment paid. Confirmation requires a matching authenticated MiCash status API response and successful local storage. Background checks use WordPress cron, approximately every five minutes when cron runs, up to 2304 attempts. Check status in admin can retry after that limit.

== Installation ==

1. In WordPress open Plugins > Add New > Upload Plugin. Select micash-payments.zip, install and activate.
2. Open MiCash Payments in the left menu.
3. Choose Sandbox / Test while integrating. Enter the Sandbox Company UUID and API key supplied for the MiCash development environment.
4. Enter the payment amount and description, enable MiCash payments, and save.
5. Open Pages > Add New. Name it Pay. Click +, add a Shortcode block and enter [micash_payment]. Publish.
6. Test the complete Sandbox flow using only provider-issued test credentials/payment details. Confirm that the same MS- reference and amount appear in WordPress and MiCash and that authenticated status verification reaches the expected terminal state.
7. When MiCash has supplied and approved live merchant credentials, enter the Production Company UUID/API key, select Production / Live, save, and perform the required live acceptance process before taking customer payments.

Switching environment changes which credentials and fixed API endpoint are used for new payments. Existing records retain their creation environment and are verified using that environment's saved credentials.

Exclude the payment page and receipt from caches. Forms expire after 30 minutes or a configuration change. South African billing and ZAR only. All pages share the same configured amount. Amounts submitted by the browser are ignored.

== External service and privacy ==

MiCash360 Privacy Policy: https://process.micash360.co.za/privacy
MiCash360 Terms of Service (End-User Agreement): https://process.micash360.co.za/terms

In Sandbox, requests are sent to https://dev.micash360.co.za. In Production, requests are sent to https://process.micash360.co.za. On submission, contact name, surname, email, phone, address, amount, description, site name, merchant reference and private return URL are sent to the selected MiCash environment over HTTPS. An API key authenticates requests. Status checks send the merchant reference to the same environment. Review the linked MiCash360 terms and privacy policy before configuring the service or submitting personal information.

The plugin stores private WordPress payment records with references, environment, amount, state, verification diagnostics, a hashed receipt token and a credential fingerprint. Billing/contact details are sent to MiCash but not persisted by this plugin. API keys remain in the WordPress settings database and must be protected with backups and administrator access controls. They are never prefilled into the admin form or exposed to visitors. Leave an API key field blank to retain its saved value.

Creation-claim records prevent duplicate submissions of the same form. A short-lived keyed IP hash limits ordinary repeated submissions; it is not a substitute for hosting-level abuse protection. Records are retained on deactivation/uninstallation for reconciliation. Receipt URLs are bearer links: do not share them or put them in analytics logs.

== Limitations and recovery ==

Only one fixed-amount offer per site. No refunds, subscriptions, carts, stock, tax calculations, invoices, email receipts or automatic fulfilment. No WooCommerce dependency. Existing WooCommerce orders are not imported or changed.

If checkout creation times out or returns an invalid response, the record needs review. It is not retried automatically because MiCash may already have created a payable request. Reconcile the MS- reference with MiCash before allowing another attempt. Reloading a page generates a new form and is NOT guaranteed to deduplicate a separate purchase intent.

If credentials for the environment used by an existing payment change, that payment cannot be checked until the matching original credentials are restored. Switching the active environment alone does not prevent old records from being verified. A process crash can leave a verification lock (micash_standalone_lock_ID). Only an administrator with database expertise should remove that exact option after confirming no verification process is running. Do not delete payment records or creation claims during reconciliation.

On playground.wordpress.net, checkout creation automatically navigates to the validated MiCash checkout URL using browser-side navigation rather than an HTTP Location redirect. A no-JavaScript fallback link is retained. This avoids Playground adding its internal /scope: prefix to an external Location redirect. Normal WordPress hosting retains the standard automatic HTTP redirect. No security headers are weakened. Persistent hosting is needed to test closed-browser cron. The matching MiCash /payments/{reference}/status endpoint must be available in the selected environment.

== Changelog ==

= 0.2.0 =
Initial WordPress.org release.
- Standalone fixed-amount ZAR payments without WooCommerce.
- Separate Sandbox and Production credentials.
- MiCash hosted checkout with authenticated payment verification.
- Payment history and manual status checks.

= 0.1.0 =
* Initial sandbox preview with fixed-amount forms, private payment records and authenticated verification.
