WooCommerce Chargeback Tracking With TrustLens: Ratios, Deadlines and Auto-Block

Most WooCommerce stores know their chargebacks are a problem, but they know it too late. By the time the dispute appears in a Stripe dashboard notification and someone manually updates a spreadsheet, the customer who filed it has already placed two more orders. The trust score that should reflect “this person has filed a dispute” still shows 65, as if nothing happened.

TrustLens solves this by listening to the same WordPress action hooks your Stripe and WooPayments gateway already fires during dispute events. The dispute ingestion is part of the free chargeback tracking module — no Pro license required, no webhook URL to configure, no cron to set up. When a dispute comes in, TrustLens hears about it through WordPress’s action system and writes the result to the customer record automatically.

This guide follows a dispute through the whole system: which hooks fire and what lands on the customer record; how TrustLens turns disputes into a chargeback ratio measured against card-network monitoring thresholds, and what to do in each state; and — on Pro — the Chargeback Monitor’s per-brand view and deadline worklist, the Dispute Evidence Report, and auto-blocking customers after lost disputes. Everything here is verified against TrustLens 1.3.23.

How Automatic Ingestion Actually Works

The TrustLens chargeback module registers hooks on WordPress’s action system during plugin initialization. When the WooCommerce Stripe plugin or WooPayments plugin receives a dispute webhook from the card network, they fire WordPress actions that TrustLens has already subscribed to. No direct Stripe API call from TrustLens, no separate webhook endpoint, no re-authentication. The gateway has already done the hard work of receiving and validating the Stripe or WooPayments webhook. TrustLens just listens to what WordPress tells it happened next.

The key thing to understand: TrustLens does not contact Stripe or WooPayments directly. It is not a Stripe app. It piggybacks on the gateway plugin’s webhook processing by hooking into the WordPress actions those plugins fire at the right moment. If the WooCommerce Stripe plugin or WooPayments plugin is installed and active, dispute events flow automatically. If you remove the gateway plugin, ingestion stops. If neither is installed, you use the manual entry form instead.

What TrustLens Listens For From Stripe

TrustLens listens to the dedicated dispute hooks the WooCommerce Stripe plugin fires: wc_stripe_charge_dispute_created when a dispute opens and wc_stripe_charge_dispute_closed when it resolves. (Versions before 1.3.10 also hooked the generic wc_gateway_stripe_process_webhook_payment action; it was removed because that action fires for successful payments, and disputes were already fully covered by the dedicated hooks.)

To find the WooCommerce order, TrustLens first reads the order ID from the dispute’s metadata, then falls back to looking up the Stripe charge ID in the _stripe_charge_id and _transaction_id order meta. If your store uses WooCommerce HPOS (High-Performance Order Storage), the lookup checks the HPOS orders meta table too. Once the order is found, TrustLens derives the customer’s email hash, records the dispute, and queues a score recalculation.

On resolution, the dispute’s final status decides the outcome: won or warning_closed (an inquiry that closed without becoming a chargeback) is recorded as won; any other closing status is recorded as lost.

What TrustLens Listens For From WooPayments

WooPayments (the Automattic-built gateway, formerly known as WooCommerce Payments) fires its own set of WordPress actions for dispute events. TrustLens hooks into woocommerce_payments_dispute_created when a dispute opens and woocommerce_payments_dispute_closed when it resolves.

The WooPayments hook carries the dispute data as an array with an order_id key, which TrustLens uses to look up the order directly. The flow from there is the same as Stripe: derive the customer email hash, record the dispute, invalidate the ratio cache, and queue a score recalculation. WooPayments dispute data also carries the evidence due date, which TrustLens stores with the dispute — that is what drives the Pro deadline countdown covered below. A dispute that closes with the status won is recorded as won; anything else as lost.

One practical note: these hooks are part of WooPayments’ integration surface rather than a private API, which keeps them stable across releases. If Automattic ever renamed them, TrustLens would need an update — as of TrustLens 1.3.23, both hook names match the current WooPayments plugin.

What Gets Written to the Customer Record

When a dispute event fires, TrustLens records five things:

First, the customer’s total_disputes counter increments in the TrustLens customers table. This is an atomic SQL UPDATE — it is not a read-then-write, so concurrent dispute events for the same customer cannot produce an inaccurate count.

Second, an event entry is written to the TrustLens events table with the event type dispute_created, the dispute ID, charge ID, amount (in store currency units, not gateway cents), dispute reason, status, and source (stripe or woopayments). This event is visible on the customer’s profile page under their event timeline, so you can see exactly when TrustLens learned about the dispute.

Third, the WooCommerce order itself gets two meta entries: _trustlens_dispute (a boolean flag) and _trustlens_dispute_data (the dispute details). This is what powers the dispute indicator on the order edit screen — a “Chargeback / dispute filed” banner showing the reason, amount and source.

Fourth, the dispute gets its own row in a dedicated disputes table: gateway, reason, amount, status and, when the gateway supplies one, the response deadline. The counters remain the source of truth for scoring; this row is what the Pro Open Disputes worklist reads.

Fifth, when the dispute closes, the disputes_won or disputes_lost counter increments on the customer record (also atomic), the dispute’s row is closed with its outcome, and a dispute_closed event is logged. The resolution triggers another score recalculation so the trust score reflects the final outcome immediately.

How Disputes Affect the Trust Score

The chargeback module’s scoring logic applies penalties based on the dispute history on each customer record. The penalty structure reflects the real-world severity of different dispute outcomes.

There is a minimum-orders gate: the chargeback module honors the same trustlens_min_orders threshold as the returns, coupons, and shipping modules. If a customer is below the minimum order count (default: 3), no scoring applies regardless of dispute history. This prevents a single legitimate dispute on a brand-new account from triggering a heavy penalty before any other behavioral signals exist.

Penalty adjustments can stack. A customer with 2 lost disputes and a 12% dispute rate across 8 orders would receive -40 (lost disputes) plus -15 (high dispute rate), placing them at -55 from the baseline before any other module signals are applied. This kind of profile is what the Critical segment is designed to surface.

Manual Entry for PayPal, Square, and Other Gateways

Not every store uses Stripe or WooPayments. PayPal, Square, Authorize.net, and offline bank-transfer gateways do not fire the WordPress hooks TrustLens listens to. For these gateways, TrustLens provides a manual chargeback recording form on the WooCommerce order edit screen.

The form appears below the billing address on any order that doesn’t already have a dispute recorded. It is collapsed by default behind a “Record manual chargeback” button. Clicking it reveals fields for the dispute amount (pre-filled with the order total), card brand (Unknown, Visa, Mastercard, Amex, Discover or Other), reason, outcome (Pending, Lost or Won), and an optional “Response due by” date from the processor’s notice.

When you submit a manual chargeback, TrustLens writes exactly the same data as an automatic ingestion — the customer’s total_disputes counter increments, the event is logged to the timeline, the order gets the dispute flag, and a score recalculation is queued. The only difference is the source field in the event data is set to manual instead of stripe or woopayments.

If you know the outcome when you record it, set it: the dispute total and the won/lost counter update together in a single atomic SQL statement. Usually you won’t know yet, so record it as Pending as soon as the notice arrives: it carries the pending penalty and stays open in the Pro worklist, with its countdown if you entered the due date. When the processor decides, the dispute banner on the order shows “Mark won” and “Mark lost” buttons (added in 1.3.23); one click closes the dispute, updates the won/lost counter and queues a score recalculation. Field-by-field detail is in the manual dispute entry docs.

Card Brand Capture and Why It Matters for Ratio Math

Chargeback ratio monitoring requires more than counting disputes — it requires knowing which card network each disputed order belongs to. Each network has its own line — Visa VAMP and Mastercard ECP at 1.5%, Amex and Discover at 1.0% — and a Visa dispute counts only against the Visa ratio. If TrustLens only knew the total number of disputes without knowing the card brand split, it could not tell you which network’s line you are approaching.

The card brand capture runs at payment completion, separately from dispute ingestion. When a Stripe payment completes, TrustLens hooks into wc_stripe_payment_complete and reads the card brand from the Stripe charge response (payment_method_details.card.brand). For WooPayments, it hooks into woocommerce_payments_payment_authenticated and reads from the _stripe_card_brand order meta or the full WooPayments charge response.

The detected brand is normalized to one of six canonical values — visa, mastercard, amex, discover, other, or unknown (when no brand data is available) — and stored on the order, which is also flagged as a card transaction. When a dispute arrives later, TrustLens looks at the order’s stored card brand to bucket the dispute into the right network’s count. This is what makes per-brand ratio calculation possible without any additional API calls to Stripe.

A generic payment-complete fallback also flags orders from a few other card gateways (Authorize.Net CIM and Square’s card gateway among them) as card transactions, but usually with an unknown brand, because those gateways don’t store the brand where TrustLens reads it. Orders with an unknown brand stay out of both sides of the ratio — so in practice the ratio measures your Stripe and WooPayments card volume. Historical Sync tags the brand on past Stripe and WooPayments orders as it builds profiles; if you ran it before 15 April 2026, the card brand backfill on the Pro Chargeback Monitor page fills the gap.

How TrustLens Measures Your Chargeback Ratio

Card networks and processors don’t judge you on how many chargebacks you have, but on what share of your transactions end in one. A store processing 100 card orders a month with 2 chargebacks is at 2.0%; one processing 10,000 with 50 chargebacks is at 0.5%. The second has 25 times as many disputes and is in far better standing. Volume protects the ratio — and a slow month magnifies every dispute.

TrustLens calculates the ratio as disputes divided by card orders for the current calendar month, in your site’s timezone. The denominator counts card-transaction orders with a recorded brand and a status of Completed, Processing or Refunded; the numerator counts disputes opened in the same window. Bank transfers, cash on delivery and other non-card payments are excluded, which keeps the number comparable to how card networks measure it. It works it out per brand — Visa, Mastercard, Amex and Discover — and as a blended total.

What you see on Free

The free plugin calculates the ratio in the background but doesn’t display a ratio gauge. What it does is warn you when it matters most: as soon as any brand’s ratio for the month reaches one of its lines, the TrustLens dashboard shows an alert band — “Chargeback ratio over network threshold”, naming the program, with a prompt to review open disputes — and the status chip in the TrustLens admin header switches to “Chargeback over line”. Under every line, neither appears. Alongside that, Free gives you each customer’s dispute count and its effect on their trust score.

What you see on Pro

Pro puts the ratio on screen. The dashboard’s Command Center gets a Chargeback Ratio Monitor panel with the blended ratio, the order and dispute counts behind it, rows for up to three of the card brands you process, and a 12-month trend; free installs see a Pro preview in that spot. The TrustLens → Chargeback Monitor page adds a headline state — Healthy, Approaching threshold, or Action needed — plus the per-brand lines and trailing-30-day window covered below. The headline state compares your blended ratio with each line and reports the one you are closest to crossing (the tightest line wins a tie); the per-brand rows show which brand is responsible.

The ratio data is cached in a WordPress transient with a 15-minute TTL. When a new dispute is recorded — either automatically from Stripe or WooPayments, or manually through the order edit form — TrustLens clears the cache immediately, so the alert band and the Pro views reflect it on the next page load rather than waiting for the cache to expire.

For the processor side of the story — how network monitoring programs escalate and what a gateway does when your ratio stays high — see how WooCommerce chargebacks can trigger a payment gateway ban.

The Four Card-Network Lines Behind the Thresholds

Visa, Mastercard, Amex and Discover each run monitoring programs that enroll merchants whose dispute ratio crosses a line — with extra fees, extra scrutiny, and, in bad cases, the threat of losing card processing. A Visa dispute counts against your Visa ratio, not your Mastercard one. These are the four lines TrustLens tracks, with the labels and values the plugin uses:

Healthy, Approaching, Action Needed: What to Do in Each State

These three states are the headline of the Pro Chargeback Monitor page, where they come with the exact math — “2 disputes from Visa VAMP (1.50%)”, for example, or “Over the Visa VAMP line (1.50%)”. On Free, the over-the-line alert is your signal for Action needed, and its absence is all you see of the other two; the advice below applies either way.

Healthy

You are more than three disputes away from the nearest line. Nothing urgent — but this is the time to learn your baseline. Look at the customers behind the disputes you do have: each customer profile shows their dispute count and history, and on Pro the top disputed customers list ranks them. A low ratio is often concentrated in a handful of customers you could stop before they file again. It is also worth noticing whether your disputes tend to follow particular promotions, so you can plan the next one with that in mind.

Approaching threshold

Three or fewer additional disputes would cross a line this month, but nothing has been crossed yet. This is the state where action is most effective, because the month hasn’t closed and the ratio hasn’t triggered anything. (It’s a Pro signal — Free stays quiet until a line is actually crossed — so on Free, a run of disputes in a short spell is your cue to work through these steps anyway.)

Action needed

Your ratio is at or above at least one line for the current month. On Pro, the headline reads Action needed when your blended ratio reaches a line; on both Free and Pro, the dashboard alert band and header chip fire whenever any single brand’s ratio does. That doesn’t automatically mean enrollment — program rules also weigh dispute volume and, for some programs, how many months you stay elevated — but it does mean you are in the zone where enrollment can happen, and your processor will likely have noticed. Some of this month’s damage is locked in; the goal is to limit the rest and make next month different.

• Block the riskiest active customers. Filter TrustLens → Customers by the Risk or Critical segment, select the customers who have ordered this month, and use Bulk Actions → Block. Some may be false positives — you can unblock anyone at any time.
• Contact your processor first. A merchant who reports the problem with a remediation plan is in a better position than one who appears unaware until the processor raises it.
• Read the dispute reasons. Clusters of “product not received” point at fulfilment; clusters of unauthorized/fraud disputes are worth checking against whether TrustLens’s Card-Testing Defense recorded an attack around the same time.
• Plan the reset. The ratio resets on the first of the month. On Pro, Automation Rules can hold orders from Risk-segment customers for review and alert your team the moment a dispute is recorded — see the automation rules playbook.

The Chargeback Monitor Page (Pro)

The free tracking — automatic ingestion, manual entry, per-customer counters, score adjustments and the over-the-line alert — records every dispute and tells you when a line has been crossed. Pro’s TrustLens → Chargeback Monitor page is built for operating on the numbers before that: where your ratio stands, which brand is driving it, which trend you’re on, and which disputes need a response before their deadline.

The page header shows the month, the current state, and a plain-language line with the exact math (“N disputes of room to the nearest line”, “N disputes from [program]”, or “Over the [program] line”). Below it, a two-column layout:

• Hero panel: the calendar-month blended ratio with its counts (disputes / card orders), the trailing-30-day ratio, and your all-time win rate — won disputes as a share of all settled (won + lost) disputes.
• Open Disputes worklist: every open dispute sorted by deadline — covered in the next section.
• Network program progress: one row per program (Visa VAMP, Mastercard ECP, Amex, Discover) with its threshold, your current ratio for that brand, a bar showing how much of the line you’ve used, and a pill — OK, a percentage once you pass your alert threshold, Over, or No data for brands you don’t process.
• 12-month trend: your blended ratio month by month, oldest to newest. Cached for up to an hour and cleared whenever a dispute is recorded. A ratio that has drifted up for three months is a bigger problem than a one-month spike.
• All-time outcomes: total, won, lost and pending disputes, customers affected, and win rate.
• Recent activity: the ten latest dispute openings and closings, grouped by day, each with the order link, amount, customer, card brand, reason and source; closures are marked Won or Lost.
• Top disputed customers: the five customers with the most disputes, with a Blocked pill where it applies and an “Evidence →” link to their Dispute Evidence Report.
• Chargeback settings: the auto-block threshold, the ratio alert threshold, and the “Verify dispute reports” toggle for evidence-report verification.

A card brand backfill sits at the foot of the page for stores that ran Historical Sync before 15 April 2026. The full screen-by-screen reference is in the Chargeback Monitor docs.

Daily ratio email alerts

Once a day, Pro checks each program’s calendar-month ratio. When any program reaches your alert threshold — 70% of its line by default, adjustable from 50% to 100% in the Chargeback settings card — or crosses it, TrustLens emails the site admin address with the brand’s ratio, the program’s threshold and a link to the Monitor. Each program alerts at most once per calendar month, so a bad stretch doesn’t flood your inbox.

The alert and the Approaching state are separate signals. The alert fires at a percentage of the line; Approaching fires when you’re within three disputes of it. A high-volume store usually gets the email first, weeks before Approaching; a low-volume store may see Approaching first. If a single dispute can swing your ratio, a lower alert threshold buys more lead time. Details: ratio email alerts docs.

The Open Disputes Worklist and Deadline Alerts (Pro)

Every dispute comes with a response window, and missing it can cost you the chance to contest the case at all. A processor email that reads “Dispute received for order #4472” is easy to bury. The Open Disputes worklist keeps every open case and its deadline in one place, at the top of the Monitor’s left column.

It lists every dispute that hasn’t closed with a won or lost outcome. Disputes with a known deadline come first, soonest at the top; disputes without one follow, oldest first. Each row shows:

• Deadline — a color-coded countdown (below)
• Customer — the customer’s email
• Order — linked to the WooCommerce order
• Amount and Reason — the reason in plain words
• Source — Stripe, WooPayments or Manual
• Actions — an “Evidence” button that opens the Dispute Evidence Report with that dispute’s order context, plus whether the report has been registered with the verification service (“Registered” or “Verify pending”)

When a dispute closes through its gateway, or you mark a manual entry won or lost on its order, it leaves the worklist and moves into the outcomes panel and activity feed. With nothing open, the worklist reads “No open disputes — you’re all clear.” For what a strong response contains once you open a case, see building a WooCommerce dispute evidence package and rebuttal.

The due-soon alert on the dashboard

The worklist only helps if you look at it, so Pro also surfaces deadlines on the TrustLens dashboard. When any open dispute is due within 72 hours (overdue ones included), an alert band at the top reads “Disputes need a response” with the count — “N disputes are due within 3 days. Respond before the deadline to keep your chance to win.” — and a “Review open disputes” button that opens the Monitor. The same band — on Free as well — flags any program whose ratio is over its network threshold. It renders nothing when everything is clear, so anything in it deserves attention.

A simple routine

• Every TrustLens visit: glance at the dashboard alert band.
• Whenever disputes are open: work the worklist top to bottom, generating the Evidence report for each case you contest.
• Weekly: check the per-brand progress bars — early in the month is when you have the most room to act.
• Monthly: read the 12-month trend and the top disputed customers list.

The Dispute Evidence Report (Pro)

When you decide to fight a dispute, the Dispute Evidence Report turns the customer’s TrustLens history into a print-ready document for the processor’s dispute portal. Opened from the disputed order, it leads with a Visa Compelling Evidence 3.0 verdict and a table of prior orders that share identifying details with the disputed one, then the trust score and signals, order history, return analysis against your store average, linked accounts and event timeline. A verification block with a SHA-256 fingerprint and QR code lets a card issuer confirm at a neutral domain that the report hasn’t been altered since it was generated.

You can open it from the worklist’s Evidence button, the TrustLens metabox on the order screen, the top disputed customers list, or the customer profile. For what each section contains, how CE3.0 qualification works, what verification does and doesn’t prove, and how to attach it to Stripe and WooPayments disputes, see how to use TrustLens’s Dispute Evidence Report to win a WooCommerce chargeback. For the broader evidence strategy, see how to win a WooCommerce chargeback dispute with evidence.

Auto-Block After N Lost Disputes (Pro)

A dispute can take weeks or months to resolve, and nothing stops the customer who filed it from ordering again in the meantime. By the time a lost outcome arrives and someone gets round to blocking the customer by hand, the next order may already have shipped. That is a timing problem, not a detection problem — TrustLens recorded the dispute and dropped the score the day it arrived. Auto-block takes the human out of that one step.

The setting lives in the Chargeback settings card on TrustLens → Chargeback Monitor, labelled “Auto-block after lost disputes”. Enter a number from 1 to 20; 0 disables it, and 0 is the default — auto-blocking is opt-in. When a dispute is recorded as lost and the customer’s lost-dispute count reaches your number, TrustLens blocks them and adds “Auto-blocked after N lost chargeback(s).” to their admin notes, so the reason is on the record.

• It acts on lost outcomes only. Pending and won disputes never count toward the number.
• It’s idempotent. An already-blocked customer isn’t blocked again.
• It acts on the customer, not the order. A blocked customer can’t complete checkout (Classic or Blocks) or add to cart on Classic pages, matched by email hash, so the same email checking out as a guest is caught too. It doesn’t cancel the disputed order or touch the dispute itself.
• It’s Pro only. TrustLens Free records disputes and adjusts scores but never blocks anyone automatically — here’s why.

What “lost” means

For Stripe disputes, any closing status other than won or warning_closed counts as lost; for WooPayments, any closing status other than won. For manual entries, it’s the outcome you select — so the count is only as accurate as what you log, and a manual entry left as Pending never counts toward the threshold.

Choosing your number

When not to automate

The failure mode of automation isn’t “it didn’t fire” — it’s “it fired on the wrong person”. Leave it off, or set it high, if your store is new and a single dispute is a large share of your history, or if your business model attracts a lot of good-faith disputes (long shipping times, made-to-order goods). Before switching it on, allowlist your best customers: TrustLens’s checkout enforcement skips allowlisted customers and keeps their score at 100, so an unlucky outcome on a long-standing VIP never stops them at checkout. Then check the blocked list now and then; if you find a block you’d have reversed, unblock in one click and raise the number.

The setting or an automation rule?

Pro Automation Rules can block too, but their dispute triggers (Dispute Recorded, Chargeback Filed) fire when a dispute is filed, not when it’s decided. That makes rules the tool for graduated responses to filing patterns — hold orders for review once a customer’s Total Disputes reaches 2, say, or block only if they’re also in a low-trust segment — and the dedicated setting the tool for reacting to lost outcomes. The automation rules playbook walks through ready-made rules for the hold-and-review rungs below a block.

Frequently Asked Questions