Stripe WooPayments Ingestion
3 min read
Stores using Stripe or WooPayments get automatic chargeback ingestion in both Free and Pro tiers. TrustLens listens for dispute webhooks delivered by the gateway, maps them to the corresponding WooCommerce order, attributes them to the right customer, and updates the customer’s record and the store-wide ratio in near-real time. This page describes exactly what TrustLens captures and how to verify ingestion is working.
What Triggers Ingestion #
When a dispute is filed against a Stripe or WooPayments transaction, the gateway fires a webhook to your WordPress site. TrustLens subscribes to:
charge.dispute.created— initial dispute filingcharge.dispute.updated— status changes (under review, won, lost)charge.dispute.closed— final outcome- WooPayments equivalents via the
woocommerce_woopayments_dispute_*action hooks
Each event triggers the ingestion flow described below.
What Gets Captured #
For each dispute event:
| Field | Source |
|---|---|
| Dispute ID | Gateway-provided unique ID |
| Order ID | Looked up via gateway transaction ID → WooCommerce order metadata |
| Customer email hash | Derived from the order’s billing email |
| Card brand | Gateway-provided (Visa, Mastercard, Amex, Discover, etc.) |
| Last 4 | Gateway-provided (used for payment-method fingerprinting in Linked Accounts) |
| Dispute reason | Gateway-provided reason code (fraudulent, product not received, etc.) |
| Dispute amount | Gateway-provided |
| Dispute date | Gateway-provided filing date |
| Status | open / under_review / won / lost / warning |
All fields except status are immutable after capture — they represent the state of the dispute at filing. Status updates with subsequent webhooks.
The Mapping Flow #
Step by step when a dispute webhook arrives:
- TrustLens receives the webhook payload
- Extracts the gateway transaction ID
- Looks up the WooCommerce order by transaction ID (using gateway’s stored meta)
- If order not found, logs a warning and creates an orphan dispute record (visible in the chargeback list but unlinked from any customer)
- Reads the order’s billing email and computes the customer email hash
- Looks up or creates the customer record
- Inserts the dispute into
{prefix}trustlens_disputes - Increments the customer’s
total_disputes,disputes_won, ordisputes_lostas appropriate - Queues a score recalculation for the customer
- Fires the
trustlens/dispute_recordedandtrustlens/chargeback_filedactions — automation rules and notifications subscribe
Verifying Ingestion Is Working #
Three sanity checks:
1. Check Recent Disputes #
Go to TrustLens → Settings → Chargebacks (Free) or Chargeback Monitor (Pro). You should see recent disputes listed with brand, amount, and status. If you have known recent disputes and the list is empty, ingestion isn’t running.
2. Verify the Webhook Endpoint #
Stripe sends webhooks to your WooCommerce Stripe webhook endpoint. In your Stripe Dashboard:
- Go to Developers → Webhooks
- Find the endpoint matching your WooCommerce installation
- Check Recent Events — successful 200 responses mean delivery is working
- If you see failures (4xx or 5xx), the endpoint isn’t responding correctly
3. Check the Action Scheduler Queue #
Go to WooCommerce → Status → Scheduled Actions, filter to the trustlens/calculate_score hook. After a dispute webhook arrives, you should see a queued action for the affected customer.
What If a Dispute Doesn’t Appear #
Common causes:
- Webhook signing key mismatch. Stripe webhooks include a signature; if the secret in WooCommerce Stripe settings is wrong, the webhook is rejected before TrustLens sees it.
- Webhook endpoint not configured. If you’ve never configured Stripe webhooks in WooCommerce, they’re not delivered.
- Order metadata missing. If the gateway transaction ID isn’t on the order (rare, but happens on imported orders or with custom integrations), TrustLens can’t map the dispute to an order.
- Gateway not on the supported list. Only Stripe and WooPayments are auto-ingested. Other gateways need manual entry.
For the first three, fix in WooCommerce Stripe / WooPayments settings. For the fourth, see the manual dispute entry workflow.
What About Lost Disputes That Started as Won? #
Disputes can be re-opened after an initial outcome. Stripe fires additional webhook events for these, and TrustLens updates the dispute’s status. The customer’s disputes_won and disputes_lost counters adjust accordingly, and a score recalculation is queued.
If a dispute is reversed multiple times (unusual but possible), TrustLens tracks the current status only. Historical state transitions are visible in the dispute’s event log.
Dispute Reasons and the Chargeback Signal #
TrustLens captures the gateway-provided reason code but doesn’t weight signals by reason — a lost dispute is a lost dispute regardless of reason. Pro automation rules can use the reason as a condition (e.g. “if dispute reason is fraudulent, block customer immediately”). See Triggers Reference.
Webhook Security #
TrustLens delegates webhook authentication to WooCommerce’s gateway integration. Stripe webhooks are signed; the WooCommerce Stripe plugin verifies the signature before the webhook reaches TrustLens. WooPayments uses the same pattern. This means TrustLens trusts that any dispute event it sees has already been authenticated by the gateway plugin.
The implication: don’t disable signature verification in your gateway plugin. If you do, attackers could potentially inject fake dispute data into TrustLens. Verification is on by default; leave it on.
Limitations #
- One gateway per dispute. If you’ve migrated between gateways and disputes arrive for both, both ingestions work independently. There’s no cross-gateway deduplication.
- Currency conversion. Dispute amounts are stored in the gateway’s reported currency. If you operate multi-currency, the chargeback ratio dashboard uses transaction counts, not currency-adjusted values, so currency mix doesn’t affect the ratio.
- Historical disputes. Webhooks only deliver new events. To capture disputes that happened before TrustLens was installed, run Historical Sync — it pulls past Stripe disputes via the Stripe API where possible.
