Gatemi Shield Developer Reference

Namespace GatemiShield, PSR-4 classes in src/ (Plugin, Settings, Checkout_Guard, Risk_Monitor, Evidence_Recorder, Stripe_Disputes, Orders, Event_Log, Admin), no Composer. Constants GATEMI_SHIELD_VERSION, GATEMI_SHIELD_FILE, GATEMI_SHIELD_DIR. Text domain gatemi-shield.

Filters

gatemi_shield_is_ip_blocked

Override the block decision for an IP.

Argument Type
$blocked bool
$ip string
// Never block the office.
add_filter( 'gatemi_shield_is_ip_blocked', function ( $blocked, $ip ) {
	return '198.51.100.20' === $ip ? false : $blocked;
}, 10, 2 );

gatemi_shield_min_sample

The minimum sample before a rate is graded.

Argument Type
$min int — 20 for dispute and refund, 10 for failure
$metric string — dispute, refund or failure

gatemi_shield_dispute_note_pattern

The regex for gateway notes that mean a dispute. Default /b(dispute|disputed|chargeback)b/i. Only notes authored by WooCommerce are checked.

gatemi_shield_agent_user_agents

User-agent fragments (case-insensitive) that mark an AI-agent order.

add_filter( 'gatemi_shield_agent_user_agents', function ( $patterns ) {
	$patterns[] = 'MyShoppingBot';
	return $patterns;
} );

gatemi_shield_agent_signals

The agent signals found for an order; any non-empty list makes it an agent order.

Argument Type
$signals string[]
$order WC_Order

gatemi_shield_evidence

The snapshot array before it is encoded and sealed.

Argument Type
$evidence array
$order WC_Order
// Record the checkout's chosen shipping method too.
add_filter( 'gatemi_shield_evidence', function ( $evidence, $order ) {
	$evidence['shipping_method'] = $order->get_shipping_method();
	return $evidence;
}, 10, 2 );

If the result cannot be JSON-encoded, no seal is stored.

gatemi_shield_evidence_packet

The packet's lines before they are joined.

Argument Type
$lines string[]
$order WC_Order

gatemi_shield_stripe_evidence_fields

The Stripe evidence fields sent by Send evidence to Stripe. Keys are Stripe's evidence[...] names (customer_name, customer_email_address, customer_purchase_ip, billing_address, shipping_address, shipping_date, shipping_tracking_number, product_description, access_activity_log, uncategorized_text). Empty values are not sent.

Argument Type
$fields array<string,string>
$order WC_Order

gatemi_shield_stripe_dispute_order

Last chance to map a Stripe dispute to an order, after the built-in lookups fail.

Argument Type
$order `WC_Order
$dispute array — the Stripe dispute object
add_filter( 'gatemi_shield_stripe_dispute_order', function ( $order, $dispute ) {
	$charge = is_array( $dispute['charge'] ) ? $dispute['charge']['id'] : $dispute['charge'];
	$found  = wc_get_orders( array( 'meta_key' => '_my_stripe_charge', 'meta_value' => $charge, 'limit' => 1 ) );
	return $found ? $found[0] : $order;
}, 10, 2 );

Action

gatemi_shield_attack_detected

Fires each time a failed order brings the store-wide count for the last hour to or above Attack alert.

Argument Type
$count int — failed orders in the last hour

The plugin itself sends the attack email from this action, at most once an hour.

Options

Option Holds
gatemi_shield_settings The settings (see Settings)
gatemi_shield_snapshot The last scan: time, level, metrics, grades, counts
gatemi_shield_events The last 100 activity events
gatemi_shield_stripe_last_sync Time of the last successful sync
gatemi_shield_stripe_status Result of the last sync

Transients

Transient Holds
gatemi_shield_f_{md5 ip} Failure timestamps for an IP in the window
gatemi_shield_b_{md5 ip} An IP's block
gatemi_shield_store_failures Store-wide failure timestamps, last hour
gatemi_shield_attack_alerted Set for an hour after an attack email

Order meta

Key Holds
_gatemi_shield_evidence The sealed snapshot (JSON)
_gatemi_shield_evidence_hash SHA-256 of that JSON
_gatemi_shield_agent yes / no
_gatemi_shield_disputed Unix time the order was first counted as disputed
_gatemi_shield_stripe_dispute id, status, reason, amount, currency, created, due_by, livemode, and evidence_sent once sent

Checking a seal yourself:

$json  = (string) $order->get_meta( '_gatemi_shield_evidence' );
$valid = '' !== $json && hash_equals( (string) $order->get_meta( '_gatemi_shield_evidence_hash' ), hash( 'sha256', $json ) );

Cron

gatemi_shield_hourly_scan, hourly. The Stripe sync runs on it at priority 5, the risk scan at 10. Scheduled on activation, re-created on any page load if missing, cleared on deactivation.

Admin endpoints

admin-post.php action Nonce What it does
gatemi_shield_scan gatemi_shield_scan Check now
gatemi_shield_stripe_sync gatemi_shield_stripe_sync Sync disputes now
gatemi_shield_evidence (GET, order_id) gatemi_shield_evidence_{id} Download the packet
gatemi_shield_stripe_evidence (POST, order_id) gatemi_shield_stripe_evidence_{id} Send evidence to Stripe as a draft

Order action key: gatemi_shield_mark_disputed. Meta boxes: gatemi-shield-evidence, gatemi-shield-stripe-dispute. Screen slug gatemi-shield.

External requests

Only https://api.stripe.com/v1/disputes (GET list, GET by id, POST evidence with submit=false), with Authorization: Bearer {key}.

Uninstall

Deletes the five options, the two store-wide transients and the cron event. Order meta is kept.

Shopping Cart
Scroll to Top