=== Allwallex Crypto Checkout ===
Requires at least: 7.0
Tested up to: 7.1.3
Requires PHP: 8.2
Requires Plugins: woocommerce
Stable tag: 0.1.0
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Hosted crypto checkout for explicit nonproduction sandbox stores.

== Description ==

Create one Allwallex payment order per store order. Classic checkout and Checkout
Blocks open the hosted payment page. Background verification binds the current
authenticated payment to the original store price, reference, asset and workspace.
Redirects and webhook claims alone never mark the store order paid.

Version 0.1.0 supports testnet integration only. It refuses a production WordPress
environment, and always labels the checkout Sandbox. Never fulfill real goods from
test payments. Mainnet activation requires a separately verified release.

Local verification: WordPress 7.1.3, WooCommerce 11.2.1, PHP 8.3.36, MySQL 8.4;
classic and Blocks checkout, legacy order storage and HPOS. Other version ranges
have not been individually tested.

== Installation ==

1. Back up your nonproduction store. Install WooCommerce and enable PHP Sodium.
2. Generate 32 random bytes, encoded as 64 hexadecimal characters. Store this
   encryption key in protected server configuration and expose it to wp-config.php:

   define('ALLWALLEX_ENCRYPTION_KEY', getenv('ALLWALLEX_ENCRYPTION_KEY'));
   define('WP_ENVIRONMENT_TYPE', 'staging');

   Keep an encrypted backup of this key separately from the database. Changing or
   losing it makes the stored credentials unreadable. Never put this key in a page,
   support ticket, source repository or public directory.

3. Upload allwallex-woocommerce-0.1.0.zip in Plugins > Add Plugin > Upload Plugin,
   then activate Allwallex Crypto Checkout.
4. In your Allwallex workspace, configure your merchant identity and issue a server
   testnet API key with orders:create and orders:read. Passkey approval is required.
5. Verify the HTTPS store website in Website Connection Center. Create a webhook
   endpoint using the receiver URL displayed in WooCommerce > Settings > Payments
   > Allwallex. Subscribe to merchant.order.* payment events.
6. Save the exact workspace UUID, API key and endpoint signing secret in the gateway
   settings. Secret inputs remain blank on later visits; blank preserves the value.
7. Choose one asset/network and an exact matching store currency. This release does
   not convert fiat prices: USD is not USDC. USDC, ETH and TRX are registered currency
   choices. WooCommerce amount precision must represent your catalogue accurately.
8. Confirm this is a sandbox store, enable the gateway and save. Send an endpoint
   test from Allwallex using the current secret, then activate webhook delivery.
   Checkout remains unavailable until the current workspace and secret pass a test.
9. Verify classic or Blocks checkout, the hosted price/network/address, a final test
   payment, the order payment record and stock. Public checkout must use HTTPS.

The default API and checkout origins are https://api.allwallex.com and
https://app.allwallex.com. Protected server constants can select separately managed
HTTPS staging services. Loopback HTTP requires ALLWALLEX_ALLOW_LOCAL_API=true and a
nonproduction WordPress environment; it exists only for isolated local verification.

== Operations ==

Keep WooCommerce Action Scheduler running through a supervised server cron. The
allwallex group processes payment events and recovers stale workers every minute.
Inspect WooCommerce > Status > Scheduled Actions and application/service alerts.
Webhook receipt acknowledges durable storage; a queued check still needs to run.

API outages and rate limits retain the original event, bounded backoff and attempt
count. Twelve failed attempts or an invalid binding require administrator review.
Use Check current Allwallex payment on the original order after restoring service.
The action requires store management permission and a fresh WordPress nonce.

After an interrupted checkout, retry the same WooCommerce order. The plugin retains
the original request before sending it and recovers the private reference. Do not
delete its records, duplicate the order or reset the request key to hide an unknown
outcome. Changed order totals require review of the original payment.

If store completion was interrupted, review the paid timestamp, transaction ID,
stock, order notes and notifications. The plugin retains a separate durable marker
and refuses to repeat an uncertain completion. STORE_COMPLETION_UNCERTAIN requires
an administrator to reconcile store effects; it is never an instruction to pay again.

Refund reservations/delivery and merchant price waivers block automatic fulfillment.
Prepare refunds in the original Allwallex order after fee review and passkey approval.
This plugin does not implement WooCommerce process_refund or create store cash
refunds, stock returns or accounting adjustments automatically. After refund review
or cancellation, resume store fulfillment manually if appropriate. Explicitly
cancelled/refunded store orders are never reopened by a later payment event.

Replacing a webhook secret retains the prior secret for 24 hours. Send a new endpoint
test with the current secret before checkout is available again. Replacing a server
API key preserves private-reference recovery for the same workspace. Never change
the workspace of an order with a pending payment.

Back up the WooCommerce database, plugin records and protected encryption key. Plugin
deactivation stops recurring recovery but retains financial history for reconciliation.
Do not clone a connected store into another environment without first disabling its
gateway and webhook delivery; cloned private references belong to the original store.

== Privacy ==

The plugin sends order price, asset, a generated private order reference and generic
sandbox description to Allwallex. It does not send customer email, address or line
items. API and signing credentials are encrypted on the store server with Sodium
secretbox. The protected encryption key is separate from WordPress options. Buyer
payment pages and verification requests contact Allwallex; there is no third-party
analytics script in this plugin. Retained payment records must follow the operator's
documented retention and access policies.

== Changelog ==

= 0.1.0 =
* Initial sandbox package: classic/Blocks checkout, HPOS/legacy order storage,
  authenticated verification, retained request recovery, signed event queue,
  encrypted credentials and protected administrator review.
