--- title: Manual Dispute Entry description: "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…" url: "https://webstepper.io/docs/trustlens/chargeback-monitor/manual-dispute-entry/" updated: "2026-10-18" category: Chargeback Monitor --- # 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.