WebMe Carding Shield Developer Docs

Bootstrap

Entrypoint: plugins/webme-carding-shield/webme-carding-shield.php

The main file defines constants, registers a namespace autoloader, installs storage on activation, and registers the plugin coordinator on plugins_loaded.

Service Composition

WebMe\CardingShield\Plugin creates shared services after WooCommerce is detected:

EventRepository
RiskEngine
StoreApiProtection
ClassicCheckoutProtection
SettingsPage
IncidentLogPage
OrderRiskPanel

If WooCommerce is missing, the plugin stops registering checkout hooks and shows an admin warning.

Store API Flow

StoreApiProtection::register() hooks:

woocommerce_store_api_rate_limit_options
woocommerce_store_api_rate_limit_id
woocommerce_store_api_checkout_update_customer_from_request
woocommerce_store_api_checkout_order_processed

Risk is evaluated at woocommerce_store_api_checkout_update_customer_from_request, before normal Store API draft/order creation in the checkout POST flow. A block decision throws WooCommerce Store API RouteException when available, with a generic exception fallback.

After WooCommerce processes the checkout order, annotate_order() writes risk metadata and can move held orders to on-hold.

Classic Checkout Flow

ClassicCheckoutProtection::register() hooks:

woocommerce_after_checkout_validation
woocommerce_checkout_order_processed

The validation hook builds a risk context from checkout data and cart total. A block decision adds a generic checkout error. The result is temporarily stored in WooCommerce session and then written to the order after processing.

Risk Engine

RiskEngine::evaluate() returns:

{
  "score": 0,
  "level": "low|medium|high",
  "rules": [],
  "decision": "allow|monitor|hold|block"
}

Decision logic:

disabled plugin: allow
trusted bypass: allow
monitor mode: monitor
score >= high threshold: configured default action
score >= medium threshold: hold
otherwise: allow

Rules

Rule	ID	Score
IP velocity	`ip_velocity`	45
Email velocity	`email_velocity`	45
Fingerprint velocity	`fingerprint_velocity`	40
Low-value attempt	`low_value_attempt`	15
Missing browser headers	`missing_browser_headers`	15 or 35
Disposable email domain	`disposable_email`	20
Billing/shipping country mismatch	`country_mismatch`	15

Storage

Activation creates {prefix}webme_carding_shield_events:

created_at
ip_address
ip_hash
email_hash
fingerprint_hash
event_type
decision
score
rule_ids
request_path

Indexes support recent-count checks by IP hash, email hash, fingerprint hash, decision, and timestamp.

Order Meta

Risk metadata:

_webme_carding_shield_score
_webme_carding_shield_level
_webme_carding_shield_decision
_webme_carding_shield_rules
_webme_carding_shield_version

These are written through WC_Order CRUD methods for HPOS compatibility.

Security Notes

Admin pages require manage_woocommerce.
Settings use WordPress Settings API sanitization.
SQL queries use $wpdb->prepare() where dynamic values exist.
Event logs avoid raw request bodies and raw card data.
Uninstall table deletion is opt-in through delete_data_on_uninstall.

Extension Notes

No formal extension API exists yet. Future work should add filtered rule registration and decision overrides only after integration tests are in place.

Developer Documentation