---
title: Chargeback Tracking
description: Chargebacks — formal disputes filed by cardholders with their card networks — are the most expensive class of customer abuse a WooCommerce store can experience. Each one costs the original order amount plus chargeback fees ($15–$50 per dispute), and ratios…
url: "https://webstepper.io/docs/trustlens/detection-modules/chargeback-tracking/"
updated: "2026-10-18"
category: Detection Modules
---

# Chargeback Tracking

Chargebacks — formal disputes filed by cardholders with their card networks — are the most expensive class of customer abuse a WooCommerce store can experience. Each one costs the original order amount plus chargeback fees ($15–$50 per dispute), and ratios crossing card-network monitoring thresholds (Visa VAMP, Mastercard ECP, Amex, Discover) can trigger fines, processor scrutiny, or account termination. The Chargeback Tracking module records every dispute, attributes it to the right customer, checks your monthly ratio for each card network against that network's line, and contributes the strongest single class of negative signals in the TrustLens scoring engine.

Module ID: `chargebacks`. Default: enabled. Free tier (Stripe/WooPayments auto-ingestion, manual entry, a dashboard alert when your ratio crosses a network line). Pro adds the dedicated Chargeback Monitor page, per-network ratios, the open-disputes deadline worklist, Dispute Evidence Report, and email alerts.

---

## What It Observes

The module ingests dispute data from three sources:

1. **Stripe** — automatic. As long as your WooCommerce Stripe gateway is processing webhooks normally, its dispute-created and dispute-closed events flow into TrustLens within minutes of being filed
2. **WooPayments dispute events** — automatic via the WooPayments hook surface
3. **Manual entry** — for stores using PayPal, Square, offline payments, or custom gateways, disputes can be logged from the WooCommerce order screen

For each dispute the module records:

- Dispute ID (gateway-specific)
- Order ID (mapped via gateway metadata)
- Customer email hash (derived from the order's billing email)
- Card brand of the order (Visa, Mastercard, Amex, Discover — captured automatically for Stripe and WooPayments orders, or chosen in the manual form)
- Dispute reason (gateway-provided category, or your own text for manual entries)
- Dispute amount (and currency, where the gateway provides it)
- Dispute date and, where available, the response due date
- Status as reported by the gateway (for example `needs_response`), then won or lost when it closes

Dispute outcomes flow in as the dispute progresses — when Stripe or WooPayments reports the dispute closed, the module records it as won or lost automatically and updates the customer's counters.

---

## What It Signals

Like the other history modules, Chargebacks waits until the customer reaches the Full-confidence Order Threshold (default 3 orders), so a single dispute on a brand-new account doesn't trip a penalty before any other history exists. The rules below add into one signal.

### Lost Disputes (Severest)

| Trigger | Score | Reason Shown on Profile |
| --- | --- | --- |
| 3+ lost disputes | -50 | "3 chargebacks lost (major risk)" |
| 2 lost disputes | -40 | "2 chargebacks lost" |
| 1 lost dispute | -30 | "Has lost chargeback" |

A single lost dispute drops the customer at least 30 points — usually enough to push them from Normal into Caution or Risk in one event.

### Pending Disputes and Dispute Rate

| Trigger | Score | Reason Shown on Profile |
| --- | --- | --- |
| Any dispute still pending (not yet won or lost) | -20 | "1 pending dispute(s)" |
| 5+ orders and disputes on 10% or more of them | -15 (additional) | "High dispute rate: 20%" |

### Won Disputes

Disputes that you successfully reversed in your favor still produce a small penalty (the dispute was filed at all), but the magnitude is much lower than a lost dispute: a flat -5 ("Previously disputed (won)") when the customer has won disputes and no lost ones.

### Clean History (Positive)

| Trigger | Score | Reason Shown on Profile |
| --- | --- | --- |
| 10+ orders with 0 disputes | +10 | "No dispute history" |

---

## The Chargeback Ratio Alert

TrustLens captures the card brand on Stripe and WooPayments orders and works out a **monthly chargeback ratio for each card network**:

```
ratio = disputes recorded this calendar month / card orders this calendar month   (per network)
```

There is no free speedometer or gauge. In Free, TrustLens stays quiet while you are under every line, and as soon as any network's ratio reaches its line it shows:

- A **"Chargeback ratio over network threshold"** alert band on the Dashboard — "Over the line for: Visa VAMP…" — with an **Open Monitor** button
- A **"Chargeback over line"** status chip in the TrustLens header, and an entry in the notifications bell

Pro's **Chargeback Monitor** shows the ratio for each network before you get there — progress toward each line, a Healthy / Approaching threshold / Action needed headline, a trailing-30-day figure alongside the calendar month, and a 12-month trend. See [Chargeback Ratio Speedometer](/docs/trustlens/chargeback-monitor/chargeback-ratio-speedometer/).

---

## Card-Network Monitoring Thresholds

For context, the monitoring lines the module checks against (TrustLens 1.3.23 and later):

| Network | Program | Line TrustLens uses |
| --- | --- | --- |
| Visa | VAMP (Visa Acquirer Monitoring Program — replaced VDMP and VFMP in 2025) | 1.5% ("Excessive" in the US, Canada, Europe, Asia Pacific and Latin America; 2.2% in CEMEA) |
| Mastercard | ECP (Excessive Chargeback Program) | 1.5% |
| Amex | Excessive Disputes | 1.0% |
| Discover | Excessive Disputes | 1.0% |

Visa's VAMP ratio also counts fraud reports (TC40s) that card issuers send to your processor. Those never reach WooCommerce, so the Visa figure TrustLens shows is a **floor** — Visa's own number can be higher. Networks only enroll merchants above a monthly minimum number of cases, and processors often act sooner. Stores in CEMEA, or any store that needs different lines, can change them with the `trustlens/chargeback_thresholds` filter.

These thresholds are the trigger points, not the failure points — landing in a monitoring program means you get warnings, increased fees, and required remediation plans. Staying above them can lead to processor termination.

The free alert appears only once a line is crossed. Pro's Chargeback Monitor and its daily email warn earlier, at a configurable percentage of each line (default 70%) so you have lead time to react.

---

## Manual Dispute Entry

For stores not on Stripe or WooPayments, manual entry keeps the ratio and the customer's history accurate. It's free:

1. Open the order in **WooCommerce → Orders**
2. Below the billing address, click **Record manual chargeback**
3. Enter:
   - Amount (defaults to the order total)
   - Card brand (Unknown / Visa / Mastercard / Amex / Discover / Other)
   - Reason (free-form)
   - Outcome (Pending by default, or Lost / Won)
   - Response due by (optional, new in 1.3.23 — the date from the processor's notice, which puts the dispute in Pro's deadline worklist)
4. Click **Save chargeback**

Manually-entered disputes contribute to the customer's signals, the per-customer dispute history, and the ratio just like ingested ones.

When the processor decides a dispute you saved as Pending, open the order again and click **Mark won** or **Mark lost** (new in 1.3.23). The outcome is recorded once, the dispute leaves the open worklist, and the score recalculates automatically.

---

## Settings

| Setting | Default | Description |
| --- | --- | --- |
| **Auto-block after lost disputes** (Pro) | 0 (off) | If a customer accumulates this many lost disputes (1–20), automatically block them at checkout. Set on the Chargeback Monitor page; not available in Free. |
| **Ratio alert threshold** (Pro) | 70% | The Pro monitor and daily email warn when a network's ratio reaches this percentage of its line (50–100%) |
| **Module enabled** | On | Master toggle (Settings → Detection) |

---

## Common Patterns

### The Friendly-Fraud Customer

**Signature:** Customer receives the product, then files a chargeback claiming non-receipt or unauthorized transaction. Pattern repeats.

**Detection:** Lost disputes accumulate. Signals stack quickly (-30 → -40 → -50).

**Profile:** Risk after the first lost dispute, Critical as losses stack.

**Action:** Pro's Dispute Evidence Report bundles trust score, signals, matched prior orders, return history, linked accounts, and full timeline for submission as evidence in subsequent disputes.

### The Single-Dispute Risk

**Signature:** Customer with 50+ clean orders suddenly files one dispute.

**Detection:** -20 while it's pending, then -30 if it's lost (and the +10 no-dispute bonus goes away), but loyalty and account-age bonuses offset.

**Profile:** Often drops from VIP or Trusted to Normal, not all the way to Risk. The clean history provides resilience.

**Action:** Investigate before blocking — could be a legitimate dispute (bank-side fraud claim, household member ordering without permission) rather than friendly fraud.

### The Card-Testing-Then-Order Pattern

**Signature:** Card-Testing module catches a device; an order from the same checkout completes; dispute filed within 60 days.

**Detection:** The Card-Testing signal applies only while the checkout's velocity events are retained (48 hours by default), so by the time the dispute arrives the dispute signals usually carry the score. An order completed during an attack keeps a `during_attack_window` event on the timeline as evidence.

**Profile:** Risk or lower once the dispute is lost.

### The Ratio Creep

**Signature:** No single customer is dramatic, but month-over-month the ratio climbs.

**Detection:** In Pro, the Chargeback Monitor moves from Healthy to Approaching threshold and the daily email warns. In Free, nothing shows until a network line is crossed and the Dashboard alert band appears.

**Action:** Investigate dispute reasons. Common causes: misleading product descriptions, slow shipping, unclear refund policies. Fix the upstream issue.

---

## Disabling the Module

Disabling Chargebacks is not recommended — chargeback signals are the most important fraud-detection signals available, and the ratio check is critical for staying clear of card-network monitoring programs. There's effectively no realistic use case for disabling this module.

---

## Reading the Chargebacks Section of a Profile

- **Signal breakdown** shows one Chargebacks signal listing every rule that fired
- **Order screen** — each disputed order shows a "Chargeback / dispute filed" notice with the reason, amount and source, plus the Mark won / Mark lost buttons for pending manual entries
- **Event timeline** shows `dispute_created` events when a dispute is first recorded and `dispute_closed` events when it resolves (won/lost)

The Pro Dispute Evidence Report bundles all of this into a print-ready report page (use your browser's print dialog to save it as a PDF) that you can submit to your processor when responding to a dispute. See [Dispute Evidence Report](/docs/trustlens/chargeback-monitor/dispute-evidence-report/).

---

## Pro Enhancements at a Glance

The Free chargeback experience is functional but limited. Pro adds:

- **Dedicated Chargeback Monitor page** — TrustLens → Chargeback Monitor
- **Per-network ratio breakdown** against each network's line
- **12-month trend chart**
- **Trailing-30-day rolling window** alongside the calendar-month view
- **Open disputes worklist** with response deadlines, and a Dashboard alert when responses are due within 72 hours
- **Recent disputes activity feed**
- **Top-disputed customers** with one-click access to Dispute Evidence Report
- **Configurable ratio alert threshold**
- **Auto-Block After N Lost Disputes**
- **Daily ratio email alerts** deduplicated per network per month

If chargebacks are a meaningful cost center for your store — and for most mid-volume merchants, they are — Pro's chargeback features are usually the strongest single justification for upgrading.