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

Accept crypto payments in WooCommerce with XPayr's non-custodial hosted checkout, flat 0.5% fees, and real-time payment sync.

== Description ==

Stop paying high fees and start accepting crypto like it's 2026.

XPayr Crypto Gateway for WooCommerce is a non-custodial payment solution for modern merchants. Whether you sell digital goods, physical products, subscriptions, or services globally, XPayr helps connect your WooCommerce store to blockchain-based payments through a secure hosted checkout flow.

= Why Choose XPayr? =

* **Flat 0.5% Fee** — No hidden costs or complex pricing tiers. Keep more of your revenue.
* **Non-Custodial & Secure** — XPayr does not expose private keys inside your WooCommerce store. Customers complete payment through secure hosted checkout infrastructure with transparent payment status handling.
* **7+ Networks & 30+ Tokens** — Accept payments across supported blockchain networks such as Ethereum, BNB Chain, Polygon, Base, and more using popular assets like USDT, USDC, and ETH, depending on your merchant configuration.
* **Modern Checkout Experience** — Provide a hosted crypto checkout flow with WalletConnect support and a streamlined payment experience for customers.

= Powerful Features for Smart Merchants =

* **Hosted Checkout** — Redirect customers to a secure, high-conversion payment page (`/pay/ps_xxx`). No sensitive wallet data touches your server.
* **Real-Time Sync** — Orders are updated automatically through webhook callbacks and optional Thank You page API verification.
* **Webhook Support** — Receive real-time IPN callbacks from XPayr with HMAC-SHA256 signature verification.
* **Multi-Network Support** — Select from available blockchain networks and supported currencies directly in WooCommerce settings.
* **WooCommerce Blocks Compatible** — Works with both the classic checkout shortcode and the Gutenberg-based Checkout block.
* **HPOS Compatible** — Fully compatible with WooCommerce High-Performance Order Storage (custom order tables).
* **On-Chain Transparency** — Give customers and operators auditable payment tracking with blockchain-linked transaction visibility.
* **Auto-Configuration** — 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.

= Is there a live demo? =

Yes. A live WooCommerce demo is available here:

https://mbo.lol/wp/wp-login.php

A read-only demo account is displayed on the login screen. After login, you can review the XPayr gateway settings in WooCommerce > Settings > Payments > XPayr.

= 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.5 =
* Updated the public WordPress.org description copy.
* Replaced plugin directory tags with the new targeted keyword set.

= 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.
