=== Fahad HSBC Payments for WooCommerce – PayMe & Hosted Card Gateway ===
Contributors: fahadmahmood, invoicepress
Tags: hsbc, payme, woocommerce, payment gateway, hong kong
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: woocommerce
WC requires at least: 8.0
WC tested up to: 11.2
Stable tag: 2.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Accept PayMe from HSBC and hosted card payments in WooCommerce. Block and classic checkout, HPOS ready, signed webhooks and refunds. Hong Kong first.

== Description ==

HSBC Payments for WooCommerce adds two payment methods to your store, each configured under WooCommerce > Settings > Payments.

**PayMe from HSBC** (uses the PayMe for Business API)

* HKD only, as required by PayMe.
* A clean pay page with a PayCode (QR), an "Open PayMe app" button on phones, a live countdown and status.
* Orders are confirmed by HSBC's signed webhook, with a rate-limited status check as a safety net.
* Full and partial refunds from the order screen, and a manual "re-check status" button.
* Separate sandbox and live credentials, plus a "Test connection" button.

**HSBC card payments (hosted)**

* Customers enter card details on the gateway's hosted page, so card data never reaches your server.
* Orders are confirmed by reading the order back from the gateway, never by trusting the browser redirect.
* Charge immediately, or authorize now and capture when the order is completed (cancelling voids the hold).
* Optional webhook safety net and refunds from the order screen.
* Needs the gateway host, merchant ID and API password issued to you by HSBC.

**Built for modern WooCommerce**

* HSBC payment panel on every order showing references, with capture and re-check actions.
* Translation ready, with Traditional Chinese (Hong Kong) included for customer-facing text.
* Works with the block-based Cart and Checkout and the classic shortcode checkout.
* Declares compatibility with High-Performance Order Storage (HPOS).
* Secrets are masked in logs; webhook signatures and digests are verified before anything is changed.
* No third-party logos are bundled. Add your own licensed icon URL in settings.

= Disclaimer =
This is an independent integration. It is not published, endorsed or supported by HSBC. HSBC and PayMe are trademarks of their respective owners. You need your own HSBC merchant arrangements and API credentials.

== External services ==

This plugin sends order data to HSBC services when a customer pays or when you refund.

**PayMe for Business API** (HSBC)
* Used to create payment requests, check their status, cancel them and issue refunds.
* Data sent: order amount, currency, order ID, a short order description and your site's notification and return URLs; your API credentials are used to sign requests.
* Endpoints: https://api.payme.hsbc.com.hk (live) and https://sandbox.api.payme.hsbc.com.hk (test).
* Terms: https://payme.hsbc.com.hk/business-terms-and-conditions and https://payme.hsbc.com.hk/pws-privacy-security

**Hosted card gateway** (host supplied by HSBC for your merchant account)
* Used to create a hosted checkout session, read the order result and issue refunds.
* Data sent: order amount, currency, a gateway order ID, a short description, your store name and URL, and your merchant credentials. The customer's card details are entered on the gateway's page, not on your site.
* The host is the one you enter in settings. Review the terms HSBC gave you for that service.

== Installation ==

1. Upload the plugin in Plugins > Add New > Upload Plugin, then activate. WooCommerce must be active.
2. Go to WooCommerce > Settings > Payments and open PayMe from HSBC or HSBC card payments.
3. Enter your sandbox credentials, save, then press "Test connection".
4. Place a test order. Switch to live only after HSBC approves your sandbox testing.

== Frequently Asked Questions ==

= Which currencies work? =
PayMe: HKD only. Cards: the currencies enabled on your HSBC account (set them in "Allowed currencies").

= Where do I get credentials? =
PayMe: open a PayMe for Business account and register at the HSBC developer portal (develop.hsbc.com). Cards: ask your HSBC relationship manager for your gateway host, merchant ID and API password.

= Does it work with the block checkout? =
Yes, and with the classic checkout.

= The sandbox says it cannot verify the signature. =
Switch "Signing key format" between Base64 and Plain in the PayMe settings, then try again.

= Customers paid but the order did not complete. =
Your site must be reachable over HTTPS so HSBC can call the notification URL. Check security plugins and firewalls are not blocking it, and turn on the debug log under the method's Advanced settings.

= Can I refund from WooCommerce? =
Yes, use the normal Refund button on the order. PayMe refunds must be made against a completed payment.

== Changelog ==

= 2.2.0 – 2026-10-26 =
* New: order screen panel with PayMe request and transaction IDs, card gateway references, and re-check / capture buttons.
* New: card authorize-then-capture. Completing the order captures; cancelling an authorized order voids the hold.
* New: translation template (.pot) and Traditional Chinese (zh_HK) for customer-facing text.
* New: automated test suite for request signing, webhook verification and state mapping (`php tests/run.php`).
* New: coding-standards config, setup guide with go-live checklist, store icon and banner.
* Improved: block checkout hints are now translatable.
* Improved: clearer notes on orders when amounts or currencies do not match.

= 2.1.0 – 2026-10-26 =
* New: complete rewrite for the current PayMe for Business API (v0.12) with signed requests and signed webhook verification.
* New: hosted card payments through a gateway hosted checkout, confirmed by server-side order lookup.
* New: block checkout and classic checkout support; HPOS compatibility declared.
* New: modern pay page with QR code, mobile deep link, countdown, live status, dark mode and reduced-motion support.
* New: full and partial refunds from the WooCommerce order screen.
* New: separate sandbox and live credentials, "Test connection" button, masked debug logging.
* New: clean uninstall of settings and cached tokens.
* Requires WooCommerce 8.0 or newer and PHP 7.4 or newer. Tested up to WordPress 7.1 and WooCommerce 11.2.

= 2.0.0 =
* Internal pre-release.

== Upgrade Notice ==

= 2.2.0 =
Adds card authorize/capture, an order screen panel and Traditional Chinese. No settings are lost when upgrading from 2.1.0. The new card "Payment action" defaults to immediate purchase.

= 2.1.0 =
Major rewrite. This version replaces the old HSBC gateway plugin, it does not update it. Deactivate the old plugin, configure the new settings (credentials are not migrated), and run a sandbox test order before enabling live payments.
