How TrustLens Ingests WooCommerce Chargebacks From Stripe and WooPayments Automatically
Store Security · TrustLens
The Dispute That Filed Itself
When Stripe or WooPayments receives a dispute, TrustLens hears about it through the same WordPress hooks your gateway already fires. No webhook URL to configure. No API keys to paste. No manual process. This guide explains exactly what happens under the hood, what lands on the customer record, and when you need to handle things yourself.
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 explains exactly what happens during that process: which hooks fire, what data gets extracted, how it reaches the customer’s trust profile, and what the Chargeback Ratio Speedometer on your dashboard reflects. At the end we cover the manual path for gateways that don’t send WordPress-native dispute events, and what Pro’s Chargeback Monitor and Dispute Evidence Report add on top.
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.
No webhook setup required
You do not need to add a TrustLens URL to your Stripe Dashboard’s webhook endpoint list. Your existing gateway plugin (WooCommerce Stripe or WooPayments) already handles the Stripe webhook connection. TrustLens hooks into WordPress actions fired after that webhook is processed. Activation is enough — the hooks register automatically.
What TrustLens Listens For From Stripe
The WooCommerce Stripe plugin fires different action hooks depending on its version. TrustLens handles both the older-style and newer-style hooks so the ingestion works regardless of which Stripe plugin version your store runs.
For dispute creation, TrustLens listens to two hooks: wc_gateway_stripe_process_webhook_payment (used by older Stripe plugin versions) and wc_stripe_charge_dispute_created (used by newer versions). When either fires with a charge.dispute.created or dispute.created event type, TrustLens extracts the dispute data and looks up the WooCommerce order by Stripe charge ID.
That charge ID lookup first checks the _stripe_charge_id and _transaction_id post meta fields on the order. If your store uses WooCommerce HPOS (High-Performance Order Storage), it falls back to the HPOS orders table automatically. Once the order is found, TrustLens derives the customer’s email hash, records the dispute, and queues a score recalculation.
For dispute resolution, TrustLens listens to wc_gateway_stripe_process_webhook_payment with a dispute.closed event type, and to wc_stripe_charge_dispute_closed. The status on the closed dispute determines whether the outcome is recorded as won (when the status is won or warning_closed) or lost.
HPOS stores are fully supported
Dispute writes use WC_Order::update_meta_data() and WC_Order::get_meta() rather than direct post_meta calls. On HPOS stores the chargeback indicator and manual recording form both write to the correct table.
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. The outcome resolution follows the same won/lost logic.
One practical note: because WooPayments is the Automattic gateway, it fires its dispute hooks through the same system WordPress uses internally. The hooks are stable across WooPayments versions because they are part of the documented integration surface. That said, if Automattic ever renames these hooks in a future WooPayments release, TrustLens would need to be updated — as of version 1.2.5, both hook names match the current WooPayments API.
What Gets Written to the Customer Record
When a dispute event fires, TrustLens records four 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 — the red banner that says “Chargeback/Dispute Filed” with the source and reason.
Fourth, when the dispute closes, the disputes_won or disputes_lost counter increments on the customer record. This is also atomic. A resolution event triggers another score recalculation so the trust score reflects the final outcome immediately.
Pending disputes count too
A dispute that has been filed but not yet resolved is already affecting the trust score. A pending dispute applies a -20 point penalty while it is open. Once resolved, the outcome determines whether a further penalty applies or the pending penalty is replaced. This means you will see the customer’s score drop as soon as the dispute arrives, not only when the outcome is known.
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. Visa’s VDMP program uses a different threshold than Mastercard’s ECP program, and Amex and Discover have their own thresholds. If TrustLens only knew the total number of disputes without knowing the card brand split, the Speedometer could not produce meaningful per-brand status.
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 as _trustlens_card_brand. 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.
For other gateways (PayPal, Square, custom integrations), the brand detection falls back to reading the payment_method field on the WooCommerce order at payment completion time. This is less precise, but it allows partial bucketing. Stores using the manual chargeback form can also specify the card brand explicitly at entry time.
The Chargeback Ratio Speedometer (Free)
The Chargeback Ratio Speedometer appears on the TrustLens Command Center dashboard and is included in the free version of the plugin. It shows a blended calendar-month chargeback ratio — total disputes this month divided by total orders this month — alongside a status indicator keyed to the thresholds of the four major card networks.
The three statuses are Healthy, Approaching threshold, and Action needed. The thresholds TrustLens uses are the publicly documented monitoring-program entry points: Visa VDMP at 0.9%, Visa VFMP at 0.65%, Mastercard ECP at 1.5%, Amex Excessive Disputes at 1%, and Discover Excessive Disputes at 1%. These are the thresholds at which card networks enroll merchants in monitoring programs that come with escalating fees and, eventually, account termination risk.
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 Speedometer refreshes on the next page load rather than waiting for the cache to expire naturally.
Calendar month, not trailing 30 days
The free Speedometer uses calendar-month windows (disputes in January divided by orders in January). This is the standard reporting period card networks use for their monitoring programs. Pro adds a trailing-30-day window alongside the calendar view, which can be useful for spotting trends mid-month before the calendar period closes.
Understanding your chargeback exposure is closely connected to understanding which customers are driving your disputes. For a full picture of how chargebacks interact with customer trust scoring and how to read your dashboard, see how WooCommerce chargebacks can trigger a payment gateway ban — that post explains the network monitoring program timeline and what happens at each stage.
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.
| Condition | Score adjustment |
|---|---|
| Any pending (unresolved) dispute | −20 points |
| 1 lost dispute | −30 points |
| 2 lost disputes | −40 points |
| 3 or more lost disputes | −50 points (major risk) |
| Disputes won (no losses) | −5 points (slight flag) |
| Dispute rate ≥10% with 5+ orders | −15 points additional |
| 10+ orders with zero dispute history | +10 points |
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 in the billing address section of every order. It is collapsed by default and shows a “Record manual chargeback” button. Clicking it reveals fields for the dispute amount, card brand (with a Visa/Mastercard/Amex/Discover/Unknown dropdown), reason code, and outcome (Pending/Lost/Won).
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 at the time of recording (some gateways send the dispute and the final decision in the same notification), you can set it immediately. The win/loss counters update atomically in a single SQL statement rather than the two-step approach of earlier versions. If the outcome is pending, you can leave it as Pending and the form will allow you to reload and record the resolution separately once you know the result.
Keep your ratio accurate regardless of gateway
The Speedometer needs card brand data to produce per-network ratios. When recording a manual chargeback, always select the card brand if you know it. A dispute recorded as Unknown brand goes into the blended ratio count but cannot contribute to per-brand Visa, Mastercard, Amex, or Discover tracking. Most payment processor emails include the card brand on the dispute notification — it is worth noting before you close the email.
What Pro Adds: The Chargeback Monitor and Dispute Evidence Report
The free chargeback tracking — automatic ingestion from Stripe and WooPayments, manual entry for other gateways, per-customer dispute counters, score adjustments, and the blended Speedometer — gives you a complete picture of your exposure. Pro adds two tools designed for merchants who need more operational depth or who face actual network program enrollment.
The Advanced Chargeback Monitor
Pro adds a dedicated TrustLens → Chargeback Monitor admin page with per-brand ratio breakdowns (Visa VDMP, Visa VFMP, Mastercard ECP, Amex, Discover), each with its own threshold progress bar. A 12-month trend chart shows how each brand’s ratio has moved over time. A trailing-30-day window runs alongside the free calendar-month view, letting you see mid-month trends before the period closes.
The monitor also shows a recent disputes activity feed and a top-disputed customers list. One-click access from any customer in that list opens the Dispute Evidence Report for that customer. Pro also adds daily ratio email alerts: if any brand crosses the configurable warning threshold (default: the monitoring-program enrollment threshold), TrustLens sends one email per brand per calendar month. The alert deduplicates so it does not send again if the ratio stays above the threshold for weeks.
Auto-Block After N Lost Disputes is also a Pro feature. The free version records disputes and adjusts scores, but the manual review and block decision is yours to make. Pro adds a configurable threshold — for example, automatically block the customer at checkout after 2 lost disputes. The auto-block only fires on lost outcomes, not pending or won disputes, and it is idempotent: an already-blocked customer is not double-blocked.
The Dispute Evidence Report
When you are actively fighting a chargeback through your processor’s dispute resolution process, the documentation you submit can be the difference between winning and losing. Most merchants submit a screenshot of the order and a shipping confirmation. That is often not enough.
TrustLens Pro’s Dispute Evidence Report is a print-ready professional behavioral risk document generated from the customer’s full TrustLens profile. It contains: the customer’s trust score and segment, the scoring signal breakdown, full order history with completion and refund patterns, a return analysis benchmarked against your store average, linked accounts detection (whether this email shares fingerprints with other accounts), and the complete event timeline.
The report is generated from the TrustLens → Chargeback Monitor page with one click on any top-disputed customer, or from the customer profile page directly. It is formatted for submitting alongside processor dispute responses and is designed to show a pattern of behavior rather than just a single transaction snapshot. For a detailed walkthrough of how to build a strong dispute case using behavioral evidence, see how to win a WooCommerce chargeback dispute with evidence.
What processors actually want to see
Most “evidence” that merchants submit in disputes is transaction confirmation — order ID, product shipped, tracking number. That is table stakes. What makes a processor take a closer look is pattern evidence: this customer has filed disputes before, they have linked accounts, their return rate is 4x the store average, and their trust score placed them in the Risk segment before this dispute was even filed. That is the kind of behavioral context the Dispute Evidence Report is designed to surface in a format the processor can review efficiently.
Frequently Asked Questions
Does TrustLens require a Stripe webhook URL to be configured?
No. TrustLens listens to WordPress action hooks that the WooCommerce Stripe plugin fires during webhook processing. You do not need to add any TrustLens URL to your Stripe Dashboard’s webhook endpoint list. Your existing gateway plugin handles the Stripe connection. Activating TrustLens is sufficient.
Is automatic chargeback ingestion from Stripe and WooPayments included in the free version?
Yes. The chargeback tracking module — including automatic dispute ingestion from Stripe and WooPayments, manual entry for other gateways, per-customer dispute counters, score adjustments, and the dashboard Chargeback Ratio Speedometer — is part of the free TrustLens plugin. No Pro license is required for these features.
What happens when a Stripe dispute is won?
When TrustLens detects a dispute.closed event with a status of won or warning_closed, it increments the customer’s disputes_won counter and queues a trust score recalculation. A won dispute still appears as a slight negative signal (-5 points) because the customer did file a dispute — but it is meaningfully less severe than a lost dispute (-30 or more). The event is logged on the customer’s timeline with the outcome.
How quickly does the Speedometer update after a new dispute?
The ratio data is cached in a WordPress transient. When any dispute is recorded — automatically from Stripe/WooPayments or manually — TrustLens clears the cache immediately. The Speedometer reflects the new dispute on the next dashboard page load, without waiting for the 15-minute cache TTL to expire.
What if I use PayPal, Square, or an offline gateway?
TrustLens does not automatically ingest disputes from gateways that do not fire WordPress-native dispute hooks. For PayPal, Square, Authorize.net, and other gateways, use the manual chargeback recording form on the WooCommerce order edit screen. The manual entry creates exactly the same records as automatic ingestion — the only difference is the source label in the event data.
What is the Dispute Evidence Report, and is it free?
The Dispute Evidence Report is a Pro-only feature. It generates a print-ready behavioral risk document for a specific customer containing their trust score, signal breakdown, order history, return analysis compared to store average, linked accounts, and full event timeline — formatted for uploading to payment processor dispute portals. It is accessible from the Advanced Chargeback Monitor page or the customer profile page with one click.
Does the minimum orders threshold affect chargeback scoring?
Yes. The chargeback module honors the trustlens_min_orders setting (default: 3 orders) the same way the returns, coupons, and shipping anomaly modules do. A customer with fewer than 3 completed orders receives no chargeback score penalty even if a dispute is recorded. This prevents a single dispute on a new account from applying a -30 penalty before enough behavioral data exists for confident scoring.
Can TrustLens automatically block customers after a chargeback?
Auto-blocking after N lost disputes is a Pro feature. In the free version, disputes are recorded, scores are adjusted, and you decide when to manually block a customer from the customer profile or list. Pro adds a configurable threshold — for example, block automatically after 2 lost disputes. The auto-block applies to checkout so blocked customers cannot add items to cart or complete an order.
TrustLens chargeback tracking is free to install
Automatic dispute ingestion from Stripe and WooPayments, per-customer dispute history, trust score integration, and the Chargeback Ratio Speedometer are all included in the free plugin. Pro adds the Advanced Chargeback Monitor with per-brand breakdowns, daily ratio alerts, and the one-click Dispute Evidence Report for processor submissions.
Key Takeaways
- TrustLens ingests Stripe and WooPayments disputes through native WordPress action hooks — no webhook URL configuration, no API keys, no separate setup beyond activating the plugin.
- Automatic ingestion, the manual entry form for other gateways, per-customer dispute counters, score adjustments, and the Chargeback Ratio Speedometer are all included in the free version of TrustLens.
- Card brand capture runs at payment completion (from Stripe charge responses and WooPayments order meta) so the Speedometer can track per-network ratios against Visa VDMP/VFMP, Mastercard ECP, Amex, and Discover thresholds separately.
- A pending dispute applies −20 points to the trust score immediately. Lost disputes apply −30 to −50 depending on count. The Speedometer cache clears on every new dispute so the dashboard always reflects current data.
- Manual chargeback recording from the WooCommerce order edit screen creates identical records to automatic ingestion — same counters, same event log, same score trigger. Always specify the card brand if you know it, so the dispute counts toward the right network’s ratio.
- The Dispute Evidence Report (Pro) generates a print-ready behavioral risk document — trust score, signal breakdown, order history, linked accounts, event timeline — formatted for submission to payment processors during dispute resolution.
- Auto-block after N lost disputes is Pro. Free surfaces the risk and adjusts the score; you make the call on every manual block decision.
