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. The Manual Dispute Entry surface keeps your chargeback ratio accurate by letting you log disputes by hand as they happen. 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 historical disputes during initial setup

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

---

Where to Enter Disputes #

Two paths:

Free Tier #

TrustLens → Settings → Chargebacks → Record Dispute

Pro Tier #

TrustLens → Chargeback Monitor → Record Dispute (top-right button on the page)

Both paths open the same entry form.

---

The Entry Form #

Field	Required	Notes
Order ID	Yes	WooCommerce order ID; TrustLens looks up the customer automatically
Card brand	Yes	Visa / Mastercard / Amex / Discover / Other. Choose accurately — affects per-brand ratio
Dispute amount	Yes	Amount disputed, not necessarily the full order amount
Dispute date	Yes	Date the dispute was filed (not today, unless they’re the same)
Status	Yes	Open / Under Review / Won / Lost / Warning. Defaults to Open.
Reason	Optional	Free-text. “Fraudulent,” “Product not received,” “Cancelled subscription,” etc.
Notes	Optional	Internal notes for your team

After saving, the dispute appears in the dispute list, the customer’s record updates, and the chargeback ratio recalculates.

---

What Happens After You Save #

1. The dispute is written to {prefix}trustlens_disputes
2. The customer’s total_disputes increments
3. If status is Lost, disputes_lost increments; if Won, disputes_won
4. A score recalculation is queued for the customer
5. The store-wide ratio recalculates
6. The trustlens/dispute_recorded and trustlens/chargeback_filed actions fire (automation rules and notifications respond)

The manual-entry path uses the same downstream pipeline as auto-ingestion — there’s no difference in how the dispute is processed after it’s stored.

---

Editing After Entry #

To update a dispute’s status as it progresses:

1. Open the dispute list
2. Click the dispute row
3. Update the status field (e.g. Open → Won, Open → Lost)
4. Add notes if relevant (e.g. “Submitted evidence; awaiting decision”)
5. Save

The customer’s score recalculates on status change. A dispute moving from Open (-20 pending signal) to Lost (-30 signal) drops the customer further; moving to Won lifts them back.

---

Getting the Card Brand Right #

Per-brand ratios (Pro) depend on accurate brand attribution. Common mistakes:

• “Other” for unknown. If you genuinely don’t know the brand, use Other. Don’t guess — guessing pollutes the per-brand ratios.
• 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.
• Stripe ingested with “Unknown” brand. If auto-ingestion captured a dispute with brand “Unknown” because the gateway didn’t supply it, you can edit the dispute manually to correct.

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

---

The Order ID Lookup #

When you enter an order ID, TrustLens:

1. Reads the order from WooCommerce
2. Extracts the billing email
3. Hashes it and looks up the customer record
4. Pre-fills the customer name and segment for confirmation

If the order can’t be found, you’ll see an error. Common causes:

• Wrong order ID (typo, or the gateway’s transaction ID instead of WooCommerce’s order ID)
• Order deleted from WooCommerce
• HPOS / legacy order storage mismatch (rare; usually transient)

If you need to log a dispute on an order that doesn’t exist in WooCommerce (e.g. an old order that was deleted), you can use the “Orphan Dispute” option — enter the customer’s email directly and TrustLens creates a customer record without an associated order. These show up in dispute lists but won’t have the order context.

---

Bulk Import (Pro) #

For back-filling many historical disputes during initial setup, Pro adds a CSV import. Format:

order_id,brand,amount,dispute_date,status,reason
12345,visa,99.00,2024-01-15,lost,Fraudulent
12346,mastercard,55.50,2024-01-16,won,Product not received
12347,amex,225.00,2024-01-20,open,Friendly fraud

Upload the CSV at Chargeback Monitor → Import. TrustLens validates each row before importing and reports any errors (invalid order IDs, malformed dates).

---

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. Manually entering them too produces double-counting that inflates your ratio.

The dispute list shows source for each dispute (Auto / Manual), 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
• Adjust statuses for disputes that have resolved since last entry

The ratio is only as accurate as the data you put in. A skipped dispute makes your ratio falsely low; a wrong card brand pollutes per-brand reporting.