Manual Dispute Entry

Stores using PayPal, Square, offline payment, or custom payment gateways don’t get automatic dispute ingestion — those gateways either don’t fire dispute webhooks to WooCommerce, or fire them in a format TrustLens doesn’t auto-parse. Manual Dispute Entry keeps your customer records and chargeback ratio accurate by letting you log disputes by hand as they happen. It is part of the free version. This page covers when to use it, how to enter disputes correctly, and how the manually-entered data feeds into the rest of TrustLens.

---

When to Use Manual Entry #

• Your store processes payments through PayPal, Square, Authorize.net, Braintree, or any gateway that isn’t Stripe or WooPayments
• You have offline orders (phone, in-person, invoice) where a customer later files a dispute
• You operate a custom gateway with no TrustLens integration
• A Stripe webhook failed to deliver and the dispute is missing from your records
• You’re back-filling disputes from before TrustLens was installed (they count in the month you enter them)

For Stripe and WooPayments, prefer auto-ingestion — it’s faster, more reliable, and records the outcome automatically. Manual entry is the fallback.

---

Where to Enter Disputes #

Disputes are entered on the order, in both Free and Pro:

1. Open the order in WooCommerce → Orders
2. Below the billing address, click Record manual chargeback
3. Fill in the form and click Save chargeback

The button appears only to users who can manage WooCommerce, and only on orders without a recorded dispute. Once a dispute is recorded, the order shows a Chargeback / dispute filed notice instead.

---

The Entry Form #

Field	Required	Notes
Amount	Pre-filled	Starts at the order total. Change it to the disputed amount if it differs; left empty or 0, the order total is used.
Card brand	Optional	Unknown / Visa / Mastercard / Amex / Discover / Other. Choosing a brand records it on the order and marks the order as a card payment, which places the dispute in that brand’s ratio.
Reason	Optional	Free text, for example product_not_received, fraud, duplicate. Saved as “manual_entry” if left empty.
Outcome	Yes	Pending (default), Lost, or Won
Response due by	Optional	The response deadline from the processor’s notice. Puts the dispute in the Pro deadline worklist with a countdown. Added in 1.3.23.

There is no date field: the dispute is dated when you save it, and it counts toward the chargeback ratio for that month. The order and customer come from the order you are on.

---

What Happens After You Save #

1. The customer’s total_disputes increments — together with disputes_lost or disputes_won if you chose Lost or Won
2. A dispute_created event is logged on the customer’s timeline and the cached chargeback ratios are cleared
3. The order is marked as disputed and shows the “Chargeback / dispute filed” notice (“Manual entry”)
4. The dispute is written to {prefix}trustlens_disputes: open if Pending, closed if Lost or Won
5. A score recalculation is queued for the customer
6. On Pro, an outcome of Lost also checks the auto-block setting
7. The trustlens/dispute_recorded and trustlens/chargeback_filed actions fire (automation rules and notifications respond)

After this point a manual dispute is handled like an auto-ingested one: it feeds the same counters, events, ratio, and notifications.

---

Recording the Outcome Later #

A manual dispute saved as Pending has no webhook to close it, so the order screen gives you the buttons instead (since 1.3.23):

1. Open the disputed order
2. Under the dispute notice, the line “Outcome pending. When the processor decides:” shows Mark won and Mark lost
3. Click the outcome the processor gave you

TrustLens increments disputes_won or disputes_lost, closes the worklist row, logs a dispute_closed event, and queues a score recalculation. On Pro, Mark lost also checks the auto-block setting. The buttons disappear once an outcome is recorded; there is no other editing of a manual dispute after it’s saved.

On the trust score, a pending dispute costs the customer 20 points; once lost, the chargeback signal is −30 for one lost dispute (−40 for two, −50 for three or more), and a won-only history is −5. The chargeback signal applies once a customer has at least the minimum number of orders set in Settings → General.

---

Getting the Card Brand Right #

The chargeback ratio is calculated per brand, so the brand decides which ratio a dispute counts toward. Common mistakes:

• Guessing. If you genuinely don’t know the brand, leave it on Unknown. Unknown leaves the order without a brand, so the dispute counts against the customer but isn’t counted in any ratio. Other counts toward the blended ratio only.
• Confusing card brand with payment processor. PayPal isn’t a card brand; if a customer disputed through PayPal, the underlying card (Visa, Mastercard, etc.) is what matters for network thresholds.
• Order status. The ratio’s denominator only includes card orders in Processing, Completed, or Refunded status, so a dispute on an order in another status still counts in the numerator but its order doesn’t count in the denominator.

For PayPal disputes specifically, PayPal usually shows the underlying card brand on the dispute notification — use that value.

---

Disputes Without an Order #

Manual entry always starts from a WooCommerce order: there is no separate dispute form and no way to record a dispute against an email address alone. If the original order no longer exists in WooCommerce, the dispute can’t be recorded in TrustLens. TrustLens also has no CSV import for disputes.

---

Don’t Double-Enter Auto-Ingested Disputes #

If you operate a mixed gateway setup (Stripe + PayPal, for example), only manually enter PayPal disputes. Stripe disputes already arrive via auto-ingestion, and an order that already has a recorded dispute doesn’t show the manual form. Entering a dispute by hand on a Stripe order before the webhook arrives produces double-counting that inflates your ratio.

The order notice shows how each dispute was recorded (“Manual entry”, “Stripe entry”, “Woopayments entry”), and on Pro the open-disputes worklist has a Source column, so you can audit for duplicates if uncertain.

---

Periodic Audit #

For stores relying heavily on manual entry, audit periodically:

• Once a week, review the previous week’s PayPal / Square dispute notifications and confirm each is logged
• Cross-reference manually-entered disputes against your processor statement at month-end
• Record outcomes with Mark won / Mark lost for disputes that have resolved since you entered them

The ratio is only as accurate as the data you put in. A skipped dispute makes your ratio falsely low; a wrong card brand puts the dispute in the wrong network’s ratio.