=== Fauran Pay with JazzCash for WooCommerce ===
Contributors: devmubs
Tags: jazzcash, woocommerce, payment gateway, pakistan, mobile wallet
Requires at least: 6.6
Tested up to: 7.0
Requires PHP: 7.4
WC requires at least: 7.0
WC tested up to: 9.0
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Accept JazzCash Card, Mobile Account and Over-the-Counter Voucher payments in WooCommerce, with full Sandbox testing support.

== Description ==

**Fauran Pay with JazzCash for WooCommerce** connects your WooCommerce store to the [JazzCash Payment Gateway](https://sandbox.jazzcash.com.pk/SandboxDocumentation/v4.2/index.html), Pakistan's leading mobile financial services provider, letting customers pay with:

* **Credit/Debit Card** (Visa, Mastercard, via JazzCash's MPGS-powered hosted page, including 3-D Secure)
* **JazzCash Mobile Account** (mobile wallet balance)
* **Over-the-Counter Voucher** (cash payment at any JazzCash outlet)

= Why this plugin =

* **PCI-DSS friendly by design.** Card and mobile account credentials are entered on JazzCash's own hosted payment page — your server never receives, stores, or transmits cardholder data.
* **Secure Hash on every request and response.** Every outgoing request and every inbound callback is signed and verified with HMAC-SHA256, exactly as specified in the JazzCash integration guide. Responses that fail verification are rejected and never applied to an order.
* **Sandbox Mode built in.** Flip a single checkbox per gateway to test end-to-end against the JazzCash Sandbox before going live — no code changes required.
* **Clean, modern codebase.** 100% object-oriented, PSR-4 autoloaded, namespaced, and built strictly against the WordPress Plugin/WooCommerce Payment Gateway APIs. No inline CSS/JS, no direct file access, all output escaped, all input sanitized and validated.
* **HPOS ready.** Declares compatibility with WooCommerce's High-Performance Order Storage. Uses the classic (shortcode) checkout — the block-based Cart/Checkout is not yet supported, so gateways will not appear there until a dedicated Blocks integration ships in a future release.

= How it works =

1. The customer chooses Card, Mobile Account, or Voucher at WooCommerce checkout.
2. They're redirected to JazzCash's secure hosted page to authorize payment (or, for vouchers, to receive a 12-digit voucher number by SMS).
3. JazzCash posts the signed result back to your store, the Secure Hash is verified, and the order is updated automatically — no manual reconciliation.
4. For vouchers paid later at a JazzCash outlet, an Instant Payment Notification (IPN) webhook updates the order the moment JazzCash confirms settlement.

= Requirements =

* WooCommerce 7.0+
* A JazzCash Merchant account (Sandbox account is free — see [Getting Started](https://sandbox.jazzcash.com.pk/sandbox/Home/GettingStarted))
* Store currency set to PKR
* The classic (shortcode) checkout. If your theme/setup uses the WooCommerce Cart & Checkout Blocks, switch that page back to the classic `[woocommerce_checkout]` shortcode — block-based Blocks checkout support is not yet included in this release.

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/fauran-pay-with-jazzcash-for-woocommerce`, or install the zip via **Plugins > Add New > Upload Plugin**.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Go to **WooCommerce > Settings > Payments** and enable the JazzCash gateway(s) you want to offer.
4. Click into each gateway and enter your **Sandbox** credentials (Merchant ID, Password, Integrity Salt) from the JazzCash Sandbox Portal, keeping **Sandbox Mode** enabled while testing.
5. Add the store's Return URL / IPN URL shown in each gateway's description to your JazzCash Merchant/Sandbox Portal configuration.
6. Place a test order to confirm the full round trip.
7. When ready to accept real payments, enter your **Live** credentials and disable **Sandbox Mode**.

== Frequently Asked Questions ==

= Does this plugin store customer card numbers? =

No. Card and mobile-account entry happens entirely on JazzCash's hosted payment page. This plugin only ever handles the order total, a transaction reference number, and the signed pass/fail result — never a PAN, CVV, or MPIN.

= Where do I find my Merchant ID, Password, and Integrity Salt? =

Register for a free account at the [JazzCash Sandbox Portal](https://sandbox.jazzcash.com.pk/sandbox/Home/GettingStarted) to get Sandbox credentials, and complete merchant verification on the live JazzCash Merchant Portal to get Live credentials.

= What URL do I give JazzCash for the Return URL / IPN URL? =

Each gateway's settings screen displays the exact URLs to configure. They follow the pattern `https://yourstore.com/?wc-api=jazzcash_return` and `https://yourstore.com/?wc-api=jazzcash_ipn`.

= My orders aren't updating after payment — what should I check? =

Enable **Debug Log** on the gateway and review **WooCommerce > Status > Logs** (source: `jazzcash`). Most issues trace back to a mismatched Integrity Salt, an incorrect Merchant ID for the selected mode (Sandbox vs Live), or a firewall/security plugin blocking the inbound callback.

= Is this plugin affiliated with JazzCash or Mobilink Microfinance Bank? =

No. This is an independent, third-party integration built against JazzCash's published API documentation.

= Why don't the JazzCash options appear at checkout even though the currency and credentials are correct? =

Check whether your Checkout page is using the WooCommerce Cart & Checkout Blocks. This plugin currently supports the classic (shortcode) checkout only; block-based checkout support is not yet included. Edit the Checkout page and confirm it uses the classic `[woocommerce_checkout]` shortcode rather than the Checkout block.

== External services ==

This plugin connects to JazzCash's hosted payment page (Sandbox: `https://sandbox.jazzcash.com.pk/CustomerPortal/transactionmanagement/merchantform/`, Live: `https://payments.jazzcash.com.pk/CustomerPortal/transactionmanagement/merchantform/`) to process Card, Mobile Account, and Over-the-Counter Voucher transactions — this is required for the plugin's core purpose, as WooCommerce cannot process JazzCash payments without it. It sends the order amount, currency (PKR), a merchant-generated transaction reference number, the WooCommerce order number, a fixed order-description string, a request timestamp/expiry, your store's configured Merchant ID and Return URL, and (for Mobile Account/Voucher only) your configured Bank ID and Product ID, each time a customer submits checkout using a JazzCash payment method. No customer name, email, phone number, or billing address is sent. The customer's browser is then redirected to JazzCash's own hosted page to enter card or mobile account credentials directly with JazzCash; those credentials never pass through this plugin or your server. JazzCash sends a signed result back to your store's Return URL and IPN endpoint to confirm or reject the payment. This service is provided by JazzCash (Private) Limited / Mobilink Microfinance Bank: [Terms & Conditions](https://www.jazzcash.com.pk/tc), [Privacy Notice](https://www.jazzcash.com.pk/assets/documents/JCP-Customer-Privacy-Notice-30.01.26.pdf).

== Screenshots ==

1. Gateway settings screen with Sandbox Mode toggle.
2. Checkout with JazzCash Card, Mobile Account and Voucher options.
3. Order screen showing the recorded JazzCash transaction details.

== Changelog ==

= 1.0.0 =
* Renamed from "JazzCash Payment Gateway for WooCommerce" to "Fauran Pay with JazzCash for WooCommerce" prior to first public release.
* Initial release: Card, Mobile Account, and Over-the-Counter Voucher gateways.
* Sandbox/Live mode toggle per gateway.
* HMAC-SHA256 Secure Hash generation and verification on all requests/responses.
* Return URL and IPN webhook handlers with automatic order status updates.
* High-Performance Order Storage (HPOS) compatibility declaration. Classic (shortcode) checkout only in this release — block-based Cart/Checkout is not yet supported.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
