---
title: Installation Guide
description: "This guide covers the complete installation process for TrustLens, including system requirements, installation methods, post-activation setup, and troubleshooting common issues. --- ## System Requirements Before installing, verify your hosting environment meets these requirements: | Component | Minimum | Recommended |…"
url: "https://webstepper.io/docs/trustlens/getting-started/installing-trustlens/"
updated: "2026-10-18"
category: Getting Started
---

# Installation Guide

This guide covers the complete installation process for TrustLens, including system requirements, installation methods, post-activation setup, and troubleshooting common issues.

---

## System Requirements

Before installing, verify your hosting environment meets these requirements:

| Component | Minimum | Recommended | Notes |
| --- | --- | --- | --- |
| WordPress | 6.4 | 6.8+ | Tested up to WordPress 7.1 |
| WooCommerce | 8.0 | 9.5+ | Required dependency; HPOS supported |
| PHP | 7.4 | 8.1+ | PHP 8.x provides better performance |
| MySQL | 5.6 | 8.0+ | Or MariaDB 10.1+ (10.6+ recommended) |
| PHP Memory Limit | 128 MB | 256 MB+ | Higher recommended for large historical syncs |
| Action Scheduler | Bundled | — | Provided by WooCommerce; required for background scoring |

### Checking Your Environment

To verify your current versions:

1. Go to **Tools → Site Health** in your WordPress admin
2. Click the **Info** tab
3. Check the **Server** section for PHP and MySQL versions
4. Check **WordPress** and **Active Plugins** sections for WordPress and WooCommerce versions

---

## Installation Methods

### Method 1: Install from WordPress.org (Recommended)

The simplest installation method for most users:

1. Log in to your WordPress admin dashboard
2. Navigate to **Plugins → Add New**
3. In the search box, type **"TrustLens"**
4. Locate the plugin by Webstepper and click **Install Now**
5. Wait for installation to complete
6. Click **Activate**

WooCommerce must already be installed and active; the plugin checks for it on activation and will not load if WooCommerce is missing.

### Method 2: Upload via WordPress Admin

Use this method if you downloaded the plugin as a ZIP file:

1. Download the plugin ZIP from WordPress.org or your purchase receipt
2. Log in to your WordPress admin dashboard
3. Navigate to **Plugins → Add New**
4. Click the **Upload Plugin** button at the top
5. Click **Choose File** and select the downloaded ZIP
6. Click **Install Now**
7. After installation completes, click **Activate Plugin**

### Method 3: Manual FTP/SFTP Upload

For advanced users or when other methods fail:

1. Download the plugin ZIP and extract it on your computer
2. Connect to your server using an FTP client (FileZilla, Cyberduck, etc.)
3. Navigate to your WordPress installation's `/wp-content/plugins/` directory
4. Upload the entire `trustlens` folder
5. Log in to your WordPress admin dashboard
6. Navigate to **Plugins → Installed Plugins**
7. Find "TrustLens" in the list and click **Activate**

---

## What Happens on Activation

TrustLens performs several setup tasks the first time it's activated:

1. **Database tables created** — `{prefix}trustlens_customers`, `{prefix}trustlens_events`, `{prefix}trustlens_signals`, and supporting tables for the refund ledger, category and product stats, fingerprints (linked accounts), disputes, velocity tracking, automation and webhook logs, refund cases and the Store Trust Network
2. **Default options written** — sensible defaults for scoring thresholds, card-testing velocity windows, and module toggles
3. **All eight detection modules enabled** — including Card-Testing Defense, which starts protecting checkout immediately with no configuration
4. **Pseudonymization ready** — no separate keys are generated: customer identifiers and linked-account fingerprints are hashed with keyed HMAC-SHA256 using your site's existing WordPress `auth` secret key, from the first request
5. **Welcome summary email scheduled** — sent to the notification email 24 hours after activation (once TrustLens has customers to report on)
6. **HPOS compatibility declared** — TrustLens registers as HPOS-compatible so WooCommerce's HPOS check passes cleanly

No customer data is collected or sent externally during activation. All scoring and detection runs inside your install.

---

## Verifying Installation

After activation, confirm the plugin is working correctly:

1. Look for the new **TrustLens** menu item in your WordPress admin sidebar (positioned just after WooCommerce)
2. Click **TrustLens → Dashboard**
3. On a new install you should see the **Quick start** card and a **Get Started with TrustLens** screen with a **Start Historical Sync** button (and a **Skip and analyze new orders only** link)
4. Once customers exist, the Dashboard shows the Command Center with:
   - Trust Index (average trust score) with a 30-day trend
   - Customer Segments distribution (VIP / Trusted / Normal / Caution / Risk / Critical)
   - Live telemetry and Card-Testing Defense tiles
   - Detection Modules status (8 modules on/off)
   - Priority Targets high-risk customer list
   - Chargeback Ratio Monitor (Pro; Free shows an upgrade card, plus an alert band if your ratio crosses a card-network line)
   - A Historical Data Sync card showing whether past orders have been imported

### Admin Menu Structure

| Menu Item | Description | Availability |
| --- | --- | --- |
| Dashboard | Command Center — scores, segments, KPIs, high-risk list | All users with `manage_woocommerce` |
| Customers | Searchable customer list with trust scores, segments, bulk actions, and CSV export | All users |
| Refund Cases | Refund Defense case inbox | Pro only (hidden on Free) |
| Chargeback Monitor | Per-network ratio breakdown, trend chart, open-disputes worklist, dispute feed, evidence reports | Pro only (Free shows upsell screen) |
| Card-Testing Defense | Velocity thresholds, Panic Freeze, browser challenge; Pro allowlists and 24-hour attack intelligence | All users; Pro sections gated by license |
| Automation | Trigger-based automation rules | Pro only (Free shows upsell screen) |
| Settings | General, Detection, Refunds, Payments (Pro), Alerts & Reports (notifications and scheduled reports), Integrations (webhooks, REST API, Store Network), Data | All users |

---

## First-Run Configuration

TrustLens ships with production-ready defaults, so the only mandatory first-run step is running Historical Sync. Optional configuration can be done later.

### Step 1: Run Historical Sync

Without Historical Sync, TrustLens only sees customer behavior *from activation onward*. Sync reads your existing WooCommerce orders, refunds, and coupon use in small batches and builds trust profiles for every past customer. (Past disputes aren't imported; record any you need with the manual chargeback form on the order screen.)

1. Open **TrustLens → Dashboard**
2. Click **Start Historical Sync**
3. The sync starts processing immediately, a small batch of orders at a time
4. Keep a TrustLens page open while it runs — the batches are sent from your browser. If you navigate away, the sync pauses and picks up again the next time you open the Dashboard or **Settings → Data**
5. Progress is shown on the Dashboard. For stores with thousands of orders, full sync may take several hours; your storefront is not affected.

If you'd rather not import history, click **Skip and analyze new orders only** instead; you can import past orders later.

### Step 2: Review Scoring Settings (Optional)

Defaults work for most stores. To adjust:

1. Go to **TrustLens → Settings → General**
2. Adjust the **Full-confidence Order Threshold** (default 3) — below this, most detection modules wait for more history and return risk is confidence-weighted
3. Toggle **Enable Blocking** — off by default; you decide when to enable
4. Save
5. To change the return-rate levels, open **Settings → Refunds** and adjust **High risk** (default 40%) and **Critical risk** (default 60%)

### Step 3: Module Toggles (Optional)

All eight detection modules are enabled by default. To disable a module:

1. Go to **TrustLens → Settings → Detection**
2. Toggle off any module you don't want contributing signals
3. Save

Card-Testing Defense ships **enabled** with sensible thresholds. You don't need to configure anything to start blocking stolen-card attacks at checkout.

---

## Upgrading to Pro

Unlock Pro features without reinstalling:

1. Click the **Upgrade** link in the TrustLens admin header, or visit the Pricing page in your admin
2. Select your preferred license plan
3. Complete the purchase
4. Your license activates automatically via Freemius — Pro features unlock immediately

Pro unlocks: Chargeback Monitor page, Automation Rules engine, Card-Testing Pro (auto-escalation, geo-diversity, allowlists, attack history), Payment Method Controls, Scheduled Reports, 10 advanced notification types, and Slack alerts. See [Free vs Pro Features](/docs/trustlens/getting-started/free-vs-pro-features/) for the full breakdown.

---

## Troubleshooting Installation Issues

### "TrustLens requires WooCommerce" Notice

**Cause:** WooCommerce is not installed or not active.

**Fix:** Install and activate WooCommerce from **Plugins → Add New**, then reactivate TrustLens. The plugin will not load without WooCommerce.

### TrustLens Menu Not Appearing

**Possible causes:**

- **Insufficient permissions:** The menu requires the `manage_woocommerce` capability. Administrator and Shop Manager roles have this by default.
- **WooCommerce inactive:** The plugin self-disables if WooCommerce is missing.
- **Cache:** Clear caching plugins and hard-refresh (Ctrl+Shift+R / Cmd+Shift+R).

### Historical Sync Not Starting

**Possible causes:**

- **Sync page closed:** Historical Sync started from the admin runs in small batches sent by your browser. If progress has stopped, open **TrustLens → Dashboard** or **Settings → Data** and leave it open — the sync resumes from where it stopped. If it still won't move, check that a security plugin or firewall isn't blocking `admin-ajax.php` requests.
- **Memory limit too low:** Stores with many orders need at least 256 MB. Add to `wp-config.php`: `define('WP_MEMORY_LIMIT', '256M');`
- **HPOS migration in progress:** If WooCommerce is mid-HPOS-migration, wait for it to finish before syncing.

### White Screen After Activation

**Possible causes:**

- **PHP version too low:** Verify PHP 7.4+ is running. Update through your hosting control panel.
- **Memory limit exhausted:** Add to `wp-config.php`: `define('WP_MEMORY_LIMIT', '256M');`
- **PHP fatal error:** Enable WP_DEBUG to see the specific error:
  ```
  define('WP_DEBUG', true);
  define('WP_DEBUG_LOG', true);
  ```

  Check `/wp-content/debug.log` for details.

### Plugin Conflict

**Diagnosis steps:**

1. Deactivate other fraud/security plugins temporarily
2. Switch to a default theme (Twenty Twenty-Four)
3. Test whether the issue persists
4. Reactivate plugins one at a time to identify the conflict
5. Report conflicts to support with specific plugin names

### Card-Testing Defense Blocking Legitimate Customers

If real customers report checkout errors after activation:

- Check **TrustLens → Card-Testing Defense** for recent decline events
- VIP customer bypass is on by default and covers established customers (at least 3 orders by default, not in Risk or Critical) — if a regular customer is still blocked, confirm their order count and segment, and check that Panic Freeze isn't active (a freeze blocks everyone)
- Release a held device from the Card-Testing Defense page to clear its lockout
- Pro users: add the customer's fingerprint or IP to the allowlist
- Lower velocity sensitivity in **TrustLens → Card-Testing Defense** if your store has unusually bursty legitimate traffic

---

## Uninstalling the Plugin

### Deactivation (Preserves Data)

1. Navigate to **Plugins → Installed Plugins**
2. Find "TrustLens"
3. Click **Deactivate**

All customer trust data, signals, automation logs, and settings remain in the database. Reactivating restores everything.

### Complete Removal (Deletes Data)

To remove all plugin data on uninstall:

1. Navigate to **TrustLens → Settings → Data**
2. Under **Uninstall Behavior**, turn on **"Remove all TrustLens data when plugin is deleted"**
3. Save settings
4. Go to **Plugins → Installed Plugins**, deactivate, then click **Delete**

**Warning:** This permanently removes every TrustLens table — trust profiles, signal and event history, the refund ledger, linked-account fingerprints, dispute records and automation logs — plus all TrustLens settings. This action cannot be undone. (The small TrustLens markers stored on WooCommerce orders themselves are left in place.)