=== HULO Fraud Prevention ===
Contributors: huloglobal
Tags: fraud prevention, fraud detection, risk score, blocklist, payments
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 0.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Risk-scores payments before they are charged: velocity, disposable e-mails, block/allow lists, card AVS, CVC, 3-D Secure. Scores shop orders too.

== Description ==

HULO Fraud Prevention works on any WordPress site. It scores the payments taken through HULO Payments (payment forms, pay links, the hosted payment page) and can refuse the risky ones before they are charged. With WooCommerce it also scores every shop order.

* **Payments (HULO Payments):** each payment is scored before the charge is confirmed, from local data only so the payment page never waits, and scored again in full once it is paid or authorised.
* **Shop orders (WooCommerce, optional):** every order placed through the classic checkout or the Checkout block is scored in the background a few seconds later. The checkout never waits.

Each signal adds weighted points, and every weight can be changed. The total from 0 to 100 maps to low, medium, review or blocked through your own thresholds.

**Signals**

* Blocklisted e-mail, e-mail domain, IP address or IPv4/IPv6 CIDR range (manual lists, plus any feed rows an add-on syncs)
* Disposable e-mail domains (built-in list)
* Plus-addressed e-mails. Velocity is counted by canonical identity, so x+1@gmail.com, x+2@gmail.com and x.y@gmail.com are one customer
* Payment/order velocity per IP (hour and 24 hours) and per e-mail (24 hours), and daily value per e-mail, across payments and orders alike
* Identity fan-out: three or more e-mail addresses paying from one IP in 24 hours
* Value ceiling, and a high-value first purchase
* Returning customers with paid payments or orders lower the score
* Failed payments from the same IP in the last hour (declines reported by HULO Payments, and failed shop orders)
* Billing and shipping country or postcode differ
* High-risk billing countries (your list)
* E-mail domain without MX records, gibberish e-mail local parts
* Card checks recorded by HULO Payments: AVS postcode and street, CVC, a failed 3-D Secure authentication, the Radar risk level, and a card issued in another country than the billing address
* Optional IP intelligence (VPN/proxy, datacentre, IP country vs billing country), off by default

**Modes**

* Off: payments and orders are still scored (shadow), so the history has no gaps, but nothing is flagged.
* Monitor: everything is scored and logged; risky ones are flagged.
* Hold: as Monitor, and a payment that reaches the block threshold is refused before it is charged, with a neutral message to the customer. A paid shop order at the review threshold is put On hold with a note listing the signals.

**Admin (HULO → Fraud Prevention)**

* Overview, an activity log you can filter by payments or shop orders, rules and signal weights, block and allow lists, a simulator that scores a made-up payment without logging it, and a customer lookup by e-mail across payments and orders.
* With WooCommerce: a Fraud risk box on every order and a Fraud risk column in the orders list.
* A dashboard widget with the last seven days.
* Without WooCommerce, amounts use the currency you set under Settings (GBP by default).

**For developers**

* `hulo_fraud_prevention_is_assessed( $id, $source )`: true once a record (source `hulo_payments` or `woocommerce`) has been scored.
* REST: `GET /wp-json/hulo-fraud-prevention/v1/assessment/<source>/<id>` (admins), and a rate-limited public pre-check `POST /wp-json/hulo-fraud-prevention/v1/check` with `email`, `orderValue` and `countryCode`. It returns only `allowed` and `riskLevel`.
* Filters and actions: `hulo_fraud_prevention_card_checks`, `hulo_fraud_prevention_failed_payments`, `hulo_fraud_prevention_paid_count`, `hulo_fraud_prevention_signals`, `hulo_fraud_prevention_action`, `hulo_fraud_prevention_refuse_payment`, `hulo_fraud_prevention_assessed`.

= Fraud Prevention Pro =

The Pro add-on adds:

* Enforce mode. Block-level payments are refused before they are charged. Review-level payments wait in a review queue: approve captures an authorised (manual-capture) payment, and reject releases the authorisation or refunds a captured payment. With WooCommerce, risky orders wait in a "Fraud review" order status and are cancelled and refunded on reject.
* Auto-approval after a set number of hours, and blocklisting the identity on reject
* With WooCommerce, a fulfilment gate: downloads stay locked and virtual orders do not auto-complete until the order has been scored and cleared
* Nightly threat feeds (FireHOL Level 1, Spamhaus DROP, Tor exit nodes, disposable e-mail domains) and your own feed URLs
* E-mail alerts; Slack, Discord, Teams, Telegram or webhook alerts; customer messages; and a weekly report

Try Pro free for 14 days, no card: https://huloglobal.com/wordpress-plugins/fraud-prevention/

== Installation ==

1. Install this plugin from Plugins → Add New (search for "HULO Fraud Prevention"), or upload the zip, and activate it.
2. To score payments, install HULO Payments and add a payment form or pay link. To score shop orders, use WooCommerce. Either or both.
3. Open HULO → Fraud Prevention → Rules. Everything is scored in Monitor mode from the start. Adjust the thresholds and limits to suit your site.
4. Watch the Activity tab for a week and tune the weights, then switch to Hold if you want block-level payments refused.

== Frequently Asked Questions ==

= Do I need WooCommerce? =

No. On any WordPress site it scores HULO Payments payments. With WooCommerce it also scores shop orders.

= Does it slow down payments or checkout? =

No. The check before a payment uses only data already on your site (lists, recent history, cached results). The full scoring, with any lookups, runs in the background afterwards. Shop orders are scored in the background too.

= Does it refuse payments? =

Only in Hold mode (and Pro's Enforce mode), and only at the block threshold. The customer sees a neutral message that reveals nothing about the score.

= Does it send my customers' data anywhere? =

Not by default. See External services below for the two optional lookups.

= Where do the AVS and 3-D Secure results come from? =

From the card details HULO Payments stores with each payment. Without HULO Payments the card signals are simply skipped. Any other payment plugin can store the results in the `_hulo_fp_card_checks` order meta or return them from the `hulo_fraud_prevention_card_checks` filter.

== External services ==

This plugin makes no request to any payment provider itself. Two lookups can run, both only from the background scoring, never on a page a visitor loads and never in the check before a payment:

* **Stripe, through HULO Payments** (fallback only). Payments and orders taken by HULO Payments normally carry their card checks, so nothing is requested. Only when a HULO Payments Stripe payment has no stored card checks does the plugin ask HULO Payments (`hulo_payments_stripe_request()`) for that PaymentIntent, once, with the Stripe key you configured in HULO Payments. The PaymentIntent ID is sent to api.stripe.com. Switch it off under Rules → Card checks. Without HULO Payments nothing is requested. Stripe terms: https://stripe.com/legal/ssa · Privacy: https://stripe.com/privacy
* **ip-api.com**, off by default. When "Look up each new customer IP with ip-api.com" is ticked under Rules, the customer's IP address is sent to ip-api.com once per address per 30 days to learn its country and whether it is a VPN, proxy or datacentre address. Terms and privacy: https://ip-api.com/docs/legal

The MX check on e-mail domains uses your server's own DNS resolver.

== Screenshots ==

1. Overview with the last seven days.
2. The activity log for payments and orders.
3. Rules and signal weights.
4. The simulator.

== Changelog ==

= 0.1.0 =
* First release: works on any WordPress site. HULO Payments payments are scored before the charge (Hold mode refuses block-level payments) and in full after it. With WooCommerce, orders are scored in the background. Monitor and Hold modes, block and allow lists with CIDR ranges, card AVS / CVC / Radar / 3-D Secure signals, activity log, simulator, customer lookup, order box, orders list column, dashboard widget, REST routes.
