How Gatemi Shield Works

The card-testing guard

Card testing is a bot running stolen card numbers through your checkout to find the ones that work. Every attempt costs you gateway fees and pushes up your decline rate, which processors watch.

Counting. Whenever an order moves to Failed (woocommerce_order_status_failed), the plugin:

  1. Adds it to a store-wide count of failures in the last hour. When that count reaches Attack alert (default 15), it fires gatemi_shield_attack_detected and sends one email — at most one an hour — suggesting what to check.
  2. Takes the order's customer IP address and adds the failure to that IP's count for the window (default 60 minutes).
  3. When the IP reaches the limit (default 5), blocks it for the block time (default 60 minutes) and logs "5 failed payments from 203.0.113.xxx — blocked for 60 minutes."

Counts are kept in short-lived transients, not in a table.

Refusing — on every checkout path. A bot goes wherever the checkout is, so the block is checked on all three:

Path Hook What the visitor sees
Classic checkout woocommerce_checkout_process An error notice; no order is created
Checkout block / Store API woocommerce_store_api_checkout_update_order_from_request The request fails with HTTP 429 and the same message
Order-pay page woocommerce_before_pay_action An error notice

The message is: "Too many failed payment attempts. Please wait a while and try again, or contact the store." Each refusal is logged.

Because the refusal happens before the order is paid, the attempt never reaches your gateway. Users who can manage WooCommerce are never blocked.

The visitor's IP comes from WooCommerce's own geolocation helper. If your site is behind a proxy or CDN, make sure WordPress receives the visitor's real IP, or every visitor will share the proxy's address.

The early warning

Every hour, on gatemi_shield_hourly_scan, and whenever you press Check now, the plugin:

  1. Counts paid orders in the last 30 days and 24 hours, refunds in the last 30 days, failed orders in the last 24 hours, and disputed orders in the last 30 days.
  2. Works out the three rates and grades each against your thresholds — but grades it Healthy while the sample is too small to mean anything.
  3. Takes the worst grade as the store's level and saves the snapshot.
  4. If the level is worse than at the previous scan, emails you the three rates, their grades, and what to do.

What counts as a dispute

An order is counted as disputed from the first of:

  • A Stripe dispute found by the sync (dated when Stripe opened it).
  • A gateway order note containing the whole word dispute, disputed or chargeback — only notes written by the system (author WooCommerce), never ones typed by staff or customers.
  • Order actions → Gatemi Shield: mark as disputed (chargeback) on the order screen, for any gateway.

The first date is kept; later signals do not move it. The mark is _gatemi_shield_disputed on the order.

The dispute count looks up flagged orders and checks their dates in PHP rather than with a meta query, which is what makes it correct on stores that still use the older posts order storage.

Dispute evidence

When a dispute arrives weeks later, the evidence that wins it is how the order was placed — and that is gone unless somebody wrote it down at the time. When Record dispute evidence is on, every new order (woocommerce_new_order) gets a snapshot:

  • when it was captured (UTC), the order id and how it was created (created_via);
  • IP address, user agent, accepted language, referrer, request method, and the REST route when placed through an API;
  • signed-agent headers: Signature, Signature-Input, Signature-Agent;
  • whether it looks like an AI-agent order, and why;
  • customer id, billing email, billing and shipping country and postcode, payment method, currency, total, and the items (name, quantity, SKU, line total).

The seal. The snapshot is stored as JSON in _gatemi_shield_evidence, with its SHA-256 hash in _gatemi_shield_evidence_hash. The order's Dispute Evidence panel and the packet report the seal as intact if the JSON still matches the hash, or CHANGED since recording if it does not.

Sealed once. The classic checkout saves an order before its line items, so the plugin re-seals on woocommerce_checkout_order_processed (and the Store API equivalent) to include the items — but only an order sealed in the same request. A later request cannot rewrite the evidence.

Orders created in the admin also fire woocommerce_new_order, so they get a snapshot too. That request is the shop manager's, not the customer's, so for an order created in the admin the IP address and user agent are taken only from the order itself — never from the manager's browser, which would otherwise be sent to Stripe as the customer's purchase IP.

AI shopping agents

An order made by an AI agent has no human click trail. It is flagged as an agent order if any of these is true:

  • the user agent contains ChatGPT-User, OAI-, OpenAI, Google-Agent, Gemini, Perplexity, Claude-User, ClaudeBot, Anthropic, Operator or AgentKit;
  • the request carried a Signature-Agent header (the signed agent identity is kept);
  • the REST route contains /ucp/, /acp/, /agentic/ or /agent/;
  • created_via mentions acp, ucp, agent, chatgpt or gemini.

The order gets _gatemi_shield_agent = yes, one order note, and the packet says it was placed by an AI shopping agent acting for the customer.

The evidence packet

Download evidence packet on the order produces a plain-text file, dispute-evidence-order-{number}.txt, laid out for a processor's dispute form: the order (status, dates, total, payment method and transaction id, items), the customer (name, email, addresses, account, previous completed orders), how the order was placed (including WooCommerce's order-attribution session data when present, and the seal), order notes and refunds, and the sealed JSON as recorded.

Stripe dispute sync

When a key is available and Sync disputes from Stripe is on, every hour (just before the risk scan, so new disputes count straight away):

  1. The plugin asks Stripe for disputes created since one day before the last sync (120 days back the first time), up to 1,000 per run.
  2. It also re-fetches, by id, every open dispute it already knows, so a status change is seen however old the dispute is.
  3. Each dispute is linked to its order by the PaymentIntent id stored as _stripe_intent_id (WooCommerce Stripe Gateway), then by the order's transaction id matching the PaymentIntent or the charge. A developer can map other integrations with gatemi_shield_stripe_dispute_order.
  4. A new dispute: stored on the order as _gatemi_shield_stripe_dispute, counted as a dispute, noted on the order, logged, and emailed to you with the reason, amount and response deadline.
  5. A status change: noted on the order and logged.

The order gains a Stripe Dispute (Gatemi Shield) panel with the status, reason, amount, deadline and a link to the dispute in your Stripe Dashboard.

Send evidence to Stripe — as a draft

While the dispute needs a response, the panel has Send evidence to Stripe. It sends the evidence to the Stripe dispute with submit=false, so it is saved as a draft. Nothing is ever submitted for you; you review and submit it in Stripe before the deadline.

What is sent: customer name, email, purchase IP, billing and shipping addresses, shipping date (the order's completed date) and tracking number (when a shipment-tracking plugin stored one in _wc_shipment_tracking_items), a product description, an access-activity log built from the sealed record, and the full evidence packet (trimmed to 15,000 characters). If Stripe refuses, the reason is written as an order note.

What leaves your site

Only the Stripe calls above, to api.stripe.com, and only when you have a key and sync is on. The guard, the warning and the evidence recorder run entirely on your server. Nothing is sent to Gatemi.

Shopping Cart
Scroll to Top