=== Payment Gateway for ZainPay for WooCommerce ===
Contributors: ibrahimkh4l33l
Donate link: https://ibrahim.ng
Tags: woocommerce, payment gateway, zainpay, nigeria, payments
Requires at least: 6.2
Tested up to: 7.0
Stable tag: 1.0.4
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Accept payments on your WooCommerce store using ZainPay payment gateway for Nigerian businesses.

== Description ==

The Payment Gateway for ZainPay for WooCommerce plugin allows you to accept payments on your WooCommerce store using ZainPay, a leading payment processor for Nigerian businesses.

= Key Features =

* **Multiple Payment Methods**: Support for both redirect and inline payment processing
* **Secure Transactions**: Full SSL encryption and secure API communication
* **Real-time Verification**: Automatic payment verification and order status updates
* **Webhook Support**: Real-time payment notifications from ZainPay
* **Test Mode**: Complete sandbox environment for testing
* **Mobile Responsive**: Optimized for mobile and desktop checkout experiences
* **Error Handling**: Comprehensive error logging and user-friendly error messages
* **Admin Interface**: Easy configuration through WooCommerce settings

= Supported Payment Methods =

* Credit Cards (Visa, Mastercard)
* Debit Cards
* Bank Transfers

= Requirements =

* WordPress 6.2 or higher
* WooCommerce 8.0 or higher
* PHP 7.4 or higher
* SSL Certificate (required for live payments)
* ZainPay merchant account

= Getting Started =

1. Install and activate the plugin
2. Navigate to WooCommerce > Settings > Payments
3. Enable and configure the ZainPay payment method
4. Enter your ZainPay API credentials
5. Configure your preferred payment options
6. Test the integration using test mode

= ZainPay Account =

To use this plugin, you need a ZainPay merchant account. Visit [ZainPay](https://zainpay.ng) to create an account and obtain your API credentials.

= Support =

For technical support and documentation, please visit:
* [ZainPay API Documentation](https://zainpay.ng/developers)
* [WooCommerce Documentation](https://docs.woocommerce.com/)
* [Plugin Support](https://ibrahim.ng/payment-gateway-for-zainpay-for-woocommerce).

= External services =

This plugin uses external JavaScript and APIs provided by ZainPay to initialize and process payments.

When a customer selects ZainPay at checkout, the plugin loads ZainPay’s inline JavaScript files from their servers and sends payment-related information to ZainPay. This typically includes:

* Order reference and amount
* Currency
* Store ZainBox identifier
* Customer contact details (such as name, email address, and phone number)

Payment card details are handled directly by ZainPay on their secure infrastructure. This plugin does not store or process card numbers, CVV codes, or other sensitive card data on your site.

For more information about how ZainPay collects and processes personal data, please review their terms and privacy policy:

* ZainPay Privacy Policy: https://zainpay.ng/privacy-policy
* ZainPay Terms and Conditions: https://zainpay.ng/terms

== Installation ==

= Automatic Installation =

1. Login to your WordPress admin panel
2. Navigate to Plugins > Add New
3. Search for "Payment Gateway for ZainPay for WooCommerce"
4. Click "Install Now" and then "Activate"

= Manual Installation =

1. Download the plugin files
2. Upload the `payment-gateway-for-zainpay-for-woocommerce` folder to the `/wp-content/plugins/` directory
3. Activate the plugin through the 'Plugins' menu in WordPress
4. Navigate to WooCommerce > Settings > Payments to configure

= Configuration =

1. Go to WooCommerce > Settings > Payments
2. Find "ZainPay" in the payment methods list
3. Click "Set up" or "Manage"
4. Configure the following settings:
   * Enable/Disable the payment method
   * Set the payment method title and description
   * Enable test mode for testing
   * Enter your ZainPay API credentials
   * Configure payment options (redirect or inline)
   * Set up webhook URL in your ZainPay dashboard

== Frequently Asked Questions ==

= Do I need a ZainPay account to use this plugin? =

Yes, you need a ZainPay merchant account to process payments. You can sign up at [ZainPay](https://zainpay.ng).

= Is SSL required? =

Yes, SSL is required for live payments to ensure secure transmission of payment data.

= Can I test payments before going live? =

Yes, the plugin includes a test mode that allows you to test payments using ZainPay's sandbox environment.

= What currencies are supported? =

The plugin supports Nigerian Naira (NGN) and other currencies supported by ZainPay. Check with ZainPay for the complete list of supported currencies.

= How do I set up callbacks? =

In your Zainbox settings page, set the callback URL to: `https://yoursite.com/wc-api/pgzw_zainpay`

= What payment methods are supported? =

ZainPay supports credit cards, debit cards, and bank transfer payments.

= Is the plugin mobile-friendly? =

Yes, the plugin is fully responsive and optimized for mobile devices.

= How do I troubleshoot payment issues? =

1. Check your API credentials
2. Ensure callback URL is accessible
3. Review error logs in WooCommerce > Status > Logs
4. Enable WordPress debug mode for detailed error information

== Screenshots ==

1. ZainPay payment gateway settings page
2. Checkout page with ZainPay payment option
3. Inline payment form with card details
4. Redirect payment option
5. Order confirmation page
6. Admin order details with payment information

== Changelog ==

= 1.0.4 =
* Fixed: card payments failed with "Unable to process payment. Please try again." ZainPay rejects any amount containing a decimal point, so order totals are now sent as whole numbers. When rounding changes the amount, a note is added to the order recording the original total and the amount charged.
* Fixed: the payment popup never opened on block-based checkouts. The plugin's scripts were being skipped on the order pay page.
* Fixed: popup payments could not be matched back to their order. ZainPay's inline script replaces the transaction reference with one of its own, so the plugin now records that reference against the order and uses it for verification, callbacks and webhooks.
* Fixed: incoming webhooks were rejected because the reference validation pattern did not allow a character used in the plugin's own references.
* Fixed: the payment method title and description were blank on block-based checkouts.
* Fixed: transaction references were stored using post meta, which does nothing on stores running High-Performance Order Storage.
* Security: payment status checks now verify only the transaction reference recorded against the order. Previously a reference supplied by the browser was accepted, which allowed an unpaid order to be settled against an unrelated successful transaction.
* Updated compatibility for WordPress 7.0 and WooCommerce 10.9.

= 1.0.3 =
* Added Resources sidebar to the settings page.

= 1.0.2 =
* Added detailed verification API response logging for debugging
* Fixed redirect polling status handling for successful payments
* Improved callback status fallback handling in test mode

= 1.0.1 =
* Improved debug logging 
* Enhanced security with proper nonce verification and parameter sanitization.

= 1.0.0 =
* Initial release
* Basic payment processing
* Webhook support
* Test mode functionality

== Upgrade Notice ==

= 1.0.4 =
Fixes card payments failing at checkout, the popup not opening on block-based checkouts, and popup payments not being matched back to their order. Includes a security fix to payment status checks. Recommended for all users.

= 1.0.1 =
Preparations for WordPress.org submission, translation template, and automated deploy pipeline.

= 1.0.0 =
Initial release of the ZainPay WooCommerce Payment Gateway plugin.

== Additional Information ==

= Security =

This plugin follows WordPress and WooCommerce security best practices:
* All API communications are encrypted using SSL
* User inputs are properly sanitized and validated
* CSRF protection using WordPress nonces
* Secure error logging for debugging
* Separate test and live environments

= Performance =

The plugin is optimized for performance:
* Minimal database queries
* Efficient JavaScript loading
* Optimized CSS for fast rendering
* Proper caching support

= Compatibility =

Tested with:
* WordPress 6.2 - 7.0
* WooCommerce 8.0 - 10.9
* PHP 7.4 - 8.3
* Popular WordPress themes
* Common WooCommerce extensions

= Developer Information =

For developers who want to extend or customize the plugin:
* Well-documented code with inline comments
* Follows WordPress coding standards
* Includes hooks and filters for customization
* Modular architecture for easy maintenance
* Comprehensive error handling and logging

= Support and Feedback =

We value your feedback and are committed to providing excellent support:
* Report bugs or request features
* Contribute to plugin development
* Share your experience and suggestions

For technical support, please check the troubleshooting section first, then contact ZainPay support for payment-related issues or the plugin developer for integration issues.
