=== WHA Shield for WooCommerce ===
Contributors: whashield
Tags: woocommerce, fraud, fraud detection, chargeback, order screening
Requires at least: 6.0
Tested up to: 6.7
Requires PHP: 7.4
WC requires at least: 7.0
WC tested up to: 9.4
Stable tag: 1.1.0
License: GPLv3 or later
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Screens WooCommerce orders through WHA Shield's real-time fraud API at whashield.com.

== Description ==

WHA Shield for WooCommerce sends each order's real details (IP address, billing/shipping address,
email, phone, order amount, card BIN if your gateway exposes it) to `POST /api/v1/screen` at
`https://whashield.com/api/v1`, and shows the result directly on the order edit screen.

This plugin is a client for WHA Shield's own REST API. It always talks to the fixed
`https://whashield.com/api/v1` endpoint — there is no server URL to configure — so you just need
a WHA Shield account and an API key generated from its Customer Portal (API Keys) before this
plugin can do anything.

= What it does =

* Screens each order via WHA Shield's real `/api/v1/screen` endpoint, either **before payment**
  (can stop checkout outright for a BLOCK result) or **after payment** (order is already placed;
  only its status is changed, for a merchant to review).
* Shows the real result on the order edit screen: shield score, risk level, decision
  (APPROVE / REVIEW / CHALLENGE / BLOCK), the actual reasons that contributed to the score, any
  Workflow Automation rules that matched, IP geolocation/VPN-proxy-Tor flags, and card
  brand/type/issuing bank/country when your gateway exposes a BIN.
* Adds a WHA Shield column to the Orders list with a colored decision badge.
* "Report fraud" / "Report legitimate" / "Blacklist this IP" buttons send real feedback to your
  WHA Shield account via `POST /api/v1/screen/{shield_id}/feedback` — the same feedback endpoint
  the WHA Shield API documents for any integration, not a WooCommerce-specific mechanism.
* A configurable order-status mapping per decision (e.g. REVIEW/CHALLENGE -> On hold).
* An optional, lightweight client-side device fingerprint (SHA-256 hash of a handful of stable,
  non-personal browser/screen properties), sent as `device_hash`.

= What it deliberately does NOT do =

Being upfront about scope, rather than quietly under-delivering:

* **No bundled fraud logic of its own.** Every score, decision, and reason comes from your WHA
  Shield instance's own scoring engine. This plugin only collects order data and displays the
  response — it does not re-implement or second-guess WHA Shield's scoring.
* **Card BIN is opt-in and gateway-dependent.** Most WooCommerce payment gateways never expose a
  card number to WooCommerce at all (by design, for PCI compliance), so `bin_no` is only sent if
  you configure a specific order-meta key under Settings that your particular gateway happens to
  store it in. It is never guessed or fabricated. Full card numbers are never collected, stored,
  or transmitted by this plugin.
* **The device fingerprint is basic, not WHA Shield's full device intelligence.** It is a same-
  device heuristic computed in the browser, not a canvas/WebGL fingerprint, and it will be absent
  from an order if the hashing promise hasn't resolved yet by the time "Place order" is clicked
  (rare, but disclosed rather than silently claimed as 100% reliable).
* **"Before payment" blocking only ever acts on a BLOCK decision.** REVIEW/CHALLENGE never stop
  checkout — WHA Shield's own decision model treats those as "needs a human look," not "reject
  outright," and this plugin follows that distinction rather than inventing a stricter one.
* **Never blocks on an API error.** If whashield.com is unreachable or your API key is missing,
  the order proceeds normally and a note is added to the order explaining screening was skipped —
  a network hiccup should never cost you a legitimate sale.

= Requirements =

* A WHA Shield account at whashield.com.
* A WHA Shield API key with the `screen.check` scope (and `screen.feedback` if you want to use the
  review buttons), created under your WHA Shield account's API Keys page.
* WooCommerce 7.0+.

== Installation ==

1. Upload the `whashield-for-woocommerce` folder to `/wp-content/plugins/`, or install the zip via
   Plugins -> Add New -> Upload Plugin.
2. Activate the plugin. WooCommerce must already be active.
3. Go to WHA Shield (left admin menu) and enter your WHA Shield API key.
4. Choose when to screen (before or after payment) and how each decision should map to an order
   status.
5. Tick "Enable screening" and save.

== Frequently Asked Questions ==

= Does this send my customers' data to a third party? =

It sends order data (IP, billing/shipping address, email, phone, order amount, and card BIN when
your gateway exposes one) to whashield.com, the WHA Shield API this plugin is built for. Nothing is
sent anywhere else. Review WHA Shield's own privacy/data-handling terms for how that data is
processed and retained once it reaches their API.

= Why isn't the card BIN showing up? =

Because your payment gateway most likely never gives WooCommerce the card number at all (correct,
PCI-compliant behavior for most gateways). See "What it deliberately does NOT do" above.

= What happens if whashield.com is unreachable? =

Orders proceed normally with no screening; an order note records that screening was skipped and
why. Screening is never a single point of failure for checkout.

== Changelog ==

= 1.1.0 =
* The WHA Shield API is hosted at a fixed domain (whashield.com), so the "API base URL"
  settings field has been removed -- there's nothing left to configure there. Just add
  your API key. Internally the plugin now talks to https://whashield.com/api/v1.
* The optional "portal URL" field (used only for the "View full result" deep link) now
  defaults to https://whashield.com automatically.

= 1.0.1 =
* Declared compatibility with WooCommerce High-Performance Order Storage (HPOS) and
  Cart/Checkout Blocks via FeaturesUtil::declare_compatibility(), fixing the
  "some of your active plugins are incompatible" admin warning. No behavior change —
  the plugin's code already handled both; it just never told WooCommerce so.

= 1.0.0 =
* Initial release.
