=== XPayr Crypto Gateway for WooCommerce ===
Contributors: xpayr
Tags: crypto, cryptocurrency, payments, woocommerce, blockchain
Requires at least: 6.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 0.2.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Accept cryptocurrency payments in your WooCommerce store via XPayr hosted checkout sessions.

== Description ==

XPayr Crypto Gateway for WooCommerce allows merchants to accept cryptocurrency payments directly in their WooCommerce stores. Customers select the crypto payment method at checkout and are redirected to a secure, hosted XPayr payment page to complete the transaction.

= Key Features =

* **Hosted Checkout** — Redirect customers to a secure XPayr payment page (`/pay/ps_xxx`). No sensitive wallet data touches your server.
* **Automatic Order Sync** — Order status is automatically updated when payment is confirmed, failed, or expired.
* **Webhook Support** — Receive real-time IPN callbacks from XPayr with HMAC-SHA256 signature verification.
* **Thank You Page Sync** — Optionally poll the XPayr API when the customer returns to verify payment status immediately.
* **Multi-Network Support** — Select from available blockchain networks (e.g. BSC, Base, Ethereum) and currencies (USDC, USDT) directly in WooCommerce settings.
* **WooCommerce Blocks Compatible** — Works with both the classic checkout shortcode and the new Gutenberg-based Checkout block.
* **HPOS Compatible** — Fully compatible with WooCommerce High-Performance Order Storage (custom order tables).
* **Auto Webhook Registration** — Optionally auto-register the WooCommerce callback URL on XPayr and sync the webhook secret.
* **Configurable Order Status** — Choose whether completed payments set orders to "Completed" or "Processing."

== External services ==

This plugin relies on external services provided by XPayr.

= Service: XPayr API =

Used for creating payment sessions, checking payment status, listing available networks/currencies, and syncing webhook callback settings.

Data sent to the service:

* Order amount and currency
* Selected blockchain network
* WooCommerce order reference and order ID metadata
* Customer billing email
* Return/cancel/callback URLs used to complete checkout and receive updates
* API authentication key configured by the merchant

When data is sent:

* When the customer places an order with XPayr payment method
* When Thank You page sync is enabled and the order status is checked
* When webhook auto-sync is enabled in gateway settings
* When the merchant opens gateway settings and network catalog is requested

Service links:

* Website: [https://xpayr.com](https://xpayr.com)
* Terms of Service: [https://xpayr.com/legal/terms-of-service](https://xpayr.com/legal/terms-of-service)
* Privacy Policy: [https://xpayr.com/legal/privacy-policy](https://xpayr.com/legal/privacy-policy)

= Service: XPayr webhook callbacks =

Used for sending payment result updates from XPayr back to the WooCommerce store.

Data sent from the service to the store:

* Payment event type
* Session ID
* Invoice ID when available
* Payment status details
* Order reference metadata previously created for the checkout session
* HMAC signature header used for webhook verification

When data is sent:

* When XPayr sends a payment confirmation, failure, or expiration callback to the WooCommerce webhook URL configured in the plugin

Service links:

* Website: [https://xpayr.com](https://xpayr.com)
* Terms of Service: [https://xpayr.com/legal/terms-of-service](https://xpayr.com/legal/terms-of-service)
* Privacy Policy: [https://xpayr.com/legal/privacy-policy](https://xpayr.com/legal/privacy-policy)

== Installation ==

1. Upload the `xpayr-crypto-gateway-for-woocommerce` folder to `/wp-content/plugins/`.
2. Activate the plugin in WordPress Admin > Plugins.
3. Go to WooCommerce > Settings > Payments > XPayr.
4. Enable the payment method and configure:
   - **API Base URL** (default: `https://xpayr.com/api/v1`)
   - **Secret API Key** (`sk_test_...` or `sk_live_...`)
   - **Network** and **Currency** defaults
5. Save changes. The gateway will appear at checkout.

== Frequently Asked Questions ==

= What cryptocurrencies are supported? =

XPayr supports multiple stablecoins (USDC, USDT) across various blockchain networks including BSC, Base, and Ethereum. The available options depend on your XPayr merchant account configuration.

= Do I need an XPayr account? =

Yes. You need to register at [xpayr.com](https://xpayr.com) and obtain a Secret API Key to use this plugin.

= Is this plugin free? =

The plugin itself is free and open source (GPLv2). XPayr may charge transaction fees as part of their payment processing service. Please review the [XPayr Terms of Service](https://xpayr.com/legal/terms-of-service) for details.

= How does webhook verification work? =

XPayr signs webhook payloads with HMAC-SHA256 using a shared secret. The plugin verifies this signature before processing any webhook event to prevent unauthorized status changes.

= Does this work with WooCommerce Blocks checkout? =

Yes. The plugin registers as a block-compatible payment method and works with both the classic shortcode checkout and the Gutenberg-based Checkout block.

= What happens if the customer closes the payment page? =

The order will remain in "Pending" status. If the payment session expires on XPayr, a webhook callback will update the order to "Cancelled." You can also enable Thank You page sync for additional verification.

== Screenshots ==

1. XPayr gateway settings page in WooCommerce.
2. Crypto payment option displayed at checkout.
3. XPayr hosted payment page.

== Changelog ==

= 0.2.4 =
* Replaced the legacy WooCommerce `wc-api` webhook endpoint with a WordPress REST API webhook endpoint for safer request handling.
* Removed custom admin plugin row meta links that triggered unnecessary external service review warnings.

= 0.2.3 =
* Expanded `== External services ==` documentation to explicitly cover inbound webhook callbacks and admin-facing external documentation links.
* Removed hardcoded remote icon fallback from WooCommerce Blocks assets so the checkout block uses only the plugin-provided local icon URL.

= 0.2.2 =
* Added explicit `== External services ==` documentation with data flow and policy links.
* Hardened webhook payload handling with JSON parse checks plus field-level sanitization/validation.
* Added strict URL validation for plugin row meta external links derived from API Base URL.

= 0.2.1 =
* Renamed plugin to "XPayr Crypto Gateway for WooCommerce" to comply with trademark guidelines.
* Added `Requires Plugins: woocommerce` declaration.
* Applied strict prefixing (`XPAYRCGFW_`) to all globals, classes, options, and constants.

= 0.2.0 =
* Added WooCommerce Blocks (Gutenberg checkout) compatibility.
* Added HPOS (High-Performance Order Storage) compatibility declaration.
* Added automatic webhook registration and secret sync.
* Added configurable order completion status (Completed vs Processing).
* Added plugin action links (Configure) and row meta links (FAQ, API docs, Support).
* Improved network and currency catalog loading from XPayr API.
* Added fallback catalog for when API is unavailable.
* Enhanced error handling and debug logging.

= 0.1.0 =
* Initial release.
* Create XPayr payment sessions from WooCommerce checkout.
* Redirect customer to hosted XPayr checkout page.
* Store session_id, invoice_id, and payment_url in order meta.
* Optional order status sync on Thank You page.
* Basic webhook (IPN) processing.

== Upgrade Notices ==

= 0.2.0 =
Adds WooCommerce Blocks and HPOS compatibility. Recommended update for all users.
