=== Payexa Gateway for WooCommerce ===
Contributors: payexa
Tags: payment, gateway, payexa, pexn, woocommerce
Requires at least: 6.4
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.10
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Requires Plugins: woocommerce
WC requires at least: 8.0
WC tested up to: 9.0

WooCommerce payment gateway integration for Payexa with sandbox support, transaction verification, and a Persian checkout experience.

== Description ==

Payexa Gateway for WooCommerce connects a WooCommerce store to the Payexa payment service. It lets merchants send customers to Payexa for payment, verify completed transactions, and update WooCommerce orders based on the verification result.

The plugin includes sandbox support, callback verification, WooCommerce logging, block checkout support, and a Persian RTL presentation for merchants who operate Persian-language stores.

Features:

* Sends payment requests to Payexa and redirects the customer to the hosted payment page.
* Verifies the transaction before marking the WooCommerce order as paid.
* Supports an explicit production or sandbox payment environment.
* Stores transaction details in WooCommerce order meta for support and reconciliation.
* Adds frontend checkout assets only on checkout and order received pages.
* Supports the classic WooCommerce checkout and the WooCommerce blocks checkout.
* Provides a Persian RTL interface for checkout and plugin settings.
* Automatically detects the WooCommerce store currency and converts Toman amounts to Rial before sending to the gateway. The currency setting can also be set manually.

How it works:

* The plugin creates a payment request through the Payexa API.
* The customer is redirected to Payexa to complete payment.
* Payexa returns the customer to WooCommerce through the callback endpoint.
* The plugin verifies the transaction with Payexa and updates the order status.

Requirements:

* WordPress 6.4 or newer
* WooCommerce 8.0 or newer
* A Payexa merchant account and API key for live payments

== Third-Party Services ==

This plugin connects to the external Payexa payment service to create and verify payment transactions.

What the service is used for:

* Creating payment requests for WooCommerce orders
* Redirecting the customer to the Payexa hosted payment page
* Verifying completed transactions before the order is marked as paid

What data is sent when a customer starts payment:

* Order amount
* Callback URL
* A unique merchant-side order reference

What data is sent when the plugin verifies a payment:

* Payexa request order ID returned by the payment request API
* The unique verification token returned by Payexa as amount_unique

When data is sent:

* A payment request is sent when the customer places an order and chooses this gateway.
* A verification request is sent after Payexa returns the customer to the WooCommerce callback URL.

Service endpoints used by the plugin:

* https://pay.pexn.ir/v1/payment/request
* https://pay.pexn.ir/v1/payment/verify
* https://sandbox.pexn.ir/v1/payment/request
* https://sandbox.pexn.ir/v1/payment/verify

Merchant API keys are stored in WordPress and sent server-to-server in the X-API-KEY header.

Provider policies:

* Terms of service: https://pexn.ir/terms
* Privacy policy: https://pexn.ir/privacy

== Installation ==

1. Upload the `payexa-gateway` folder to the `/wp-content/plugins/` directory.
2. Activate the plugin from the WordPress admin area.
3. Make sure WooCommerce is installed and active.
4. Go to WooCommerce > درگاه پی اکسا.
5. Enter your live Payexa API key in the API Key field.
6. To use the sandbox, set the payment environment to Sandbox in the plugin settings.
7. Enable the gateway and place a test order.

== Frequently Asked Questions ==

= Does this plugin support the Payexa sandbox? =
Yes. Change the payment environment to Sandbox in the plugin settings and the plugin will use the sandbox API endpoints automatically.

= What do I need for live payments? =
You need a Payexa merchant account and a valid live API key from https://pexn.ir.

= What happens after the customer returns from Payexa? =
The plugin verifies the transaction with Payexa and then updates the WooCommerce order status based on the verification result.

= My store uses Toman. Will the plugin send the correct amount to Payexa? =
Yes. The Payexa gateway processes amounts in Iranian Rial. The plugin includes a currency setting with three options: Auto (reads the WooCommerce currency setting and multiplies by 10 when the currency is IRT), Toman (always multiplies by 10), and Rial (no conversion). Auto is the default and works for most Persian WooCommerce stores.

= Does the plugin log API activity? =
Yes. It uses the WooCommerce logger for request, response, and error events.

= Can I use this plugin without WooCommerce? =
No. WooCommerce is a required dependency for this plugin.

= When is an order marked as paid? =
The order is completed only after the verification request succeeds. If Payexa reports an already verified transaction, the plugin avoids double finalization.

== Screenshots ==

1. Payexa gateway settings page in WooCommerce admin
2. Payexa payment method during WooCommerce checkout
3. Successful return to the WooCommerce order received page after verification
4. Failed or canceled payment return flow

== Changelog ==

= 1.0.10 =
* Added an editable trust message field in admin settings — the text shown below the payment method on checkout. It can be customized or left empty to hide it.
* Gateway title and description now always read from the plugin settings page, fixing inconsistency across WooCommerce versions.

= 1.0.9 =
* Fixed connection test always failing in sandbox mode because the validate endpoint does not exist on the sandbox server.
* Fixed an undefined variable in the connection test error log introduced in 1.0.8.

= 1.0.8 =
* Added automatic fallback to native PHP cURL when a third-party plugin blocks the WordPress HTTP API, ensuring payment requests reach Payexa even on restricted hosting environments.
* Fixed a potential issue where the blocks checkout payment method could be registered more than once per request.

= 1.0.7 =
* Fixed a bug where verify returning HTTP 201 (already verified) on an unpaid order left it on-hold instead of finalizing it. Orders now complete correctly when Payexa confirms the transaction was previously verified.

= 1.0.6 =
* Fixed a bug where a second callback (customer redirect) arriving after a successful payment could set the order to on-hold or failed. Orders that are already paid are now protected from any subsequent callback overwriting their status.

= 1.0.5 =
* Added a currency setting with auto-detection, Toman (IRT), and Rial (IRR) options. Toman amounts are automatically multiplied by 10 before being sent to the Payexa gateway.

= 1.0.4 =
* Added a help icon and popup guide for the API key field in the admin settings.

= 1.0.3 =
* Made the admin connection test use the current unsaved API key and environment values from the settings form.

= 1.0.2 =
* Added an explicit production or sandbox environment setting in admin.
* Made production the safe default for new installations.
* Replaced the fake connection test with API key validation through the merchant validation endpoint.
* Removed the need to enter the sandbox token in the API key field.

= 1.0.0 =
* Initial release of the Payexa gateway for WooCommerce
* Added payment request, verification, and callback handling
* Added Persian RTL settings and checkout presentation
* Added standard WooCommerce success and failure return handling

== Upgrade Notice ==

= 1.0.10 =
Adds an editable trust message on the checkout page and fixes gateway title/description consistency across WooCommerce versions.

= 1.0.9 =
Fixes connection test in sandbox mode and a minor logging bug introduced in 1.0.8.

= 1.0.8 =
Adds automatic fallback to native cURL when a security or performance plugin blocks the WordPress HTTP API. Merchants on restrictive hosting environments should update.

= 1.0.7 =
Fixes a critical bug where orders could be left unpaid when Payexa returns HTTP 201 on verify. All merchants should update immediately.

= 1.0.6 =
Fixes a critical bug where duplicate callbacks could set a successfully paid order to on-hold or failed. All merchants should update.

= 1.0.5 =
Adds automatic Toman to Rial conversion. If your store currency is IRT the plugin now sends the correct Rial amount to Payexa without any manual configuration.

= 1.0.4 =
Adds a popup guide for getting the API key without cluttering the admin settings screen.

= 1.0.3 =
Fixes the admin connection test so it checks the current form values before settings are saved.

= 1.0.2 =
Improves payment environment safety and uses a dedicated API key validation endpoint for connection testing.

= 1.0.0 =
Initial stable release.
