# Sanctions Checker WHMCS Addon

# Description

### PUQ Sanctions Checker module **[WHMCS](https://puqcloud.com/link.php?id=77)**

##### [Order now](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/) | [FAQ/Community](https://community.puqcloud.com/)

## PUQ Sanctions Checker WHMCS Module

**PUQ Sanctions Checker** is an enterprise-grade WHMCS addon module designed to automate compliance, prevent fraud, and secure your hosting business. It screens clients against international sanctions lists, national blocklists, and fraud databases in real time or via a background queue.

The module is built with a **full-AJAX administrative interface** and integrates directly into WHMCS admin workflows (such as client profiles and ticket creation) without requiring page reloads or interrupting the customer registration process.

- - - - - -

## Key Features & Capabilities

### 1. Intelligent Three-Method Matching Engine

To prevent evasion while minimizing false positives, the module features a sophisticated, configurable matching engine:

- **Trigram Matching:** Compares name subsequences to handle typos, spelling differences, and transliteration variations (e.g., matching `Дмитрий` to `Dmitriy` or `Dmitry`).
- **Per-Word Matching:** Analyzes individual words in names to catch middle names, reverse name orders, and surname-only lists.
- **Exact Matching:** Fast lookup of exact spelling matches.
- **Adjustable Thresholds:** Custom percentage scores can be defined for trigram and per-word matching methods to fine-tune the screening sensitivity.

### 2. Multi-Source Sanctions Screening

Clients are matched against multiple authoritative databases simultaneously:

- **US Consolidated Screening List (CSL):** Direct, real-time API queries combining 11 US government lists (including OFAC SDN, State Department, and BIS Entity Lists).
- **EU Financial Sanctions Files (FSF):** Synced daily and mirrored locally into the WHMCS database from OpenSanctions.
- **Canada DFATD-SEMA List:** Canada's Special Economic Measures Act sanctions, mirrored locally.
- **Country Blocklist:** Customizable country blocklist matching against ISO-2 country codes.

### 3. Integrated Fraud Check (FraudRecord & IPQualityScore)

In addition to sanctions screening, the module performs real-time fraud checks:

- Live lookup of client details against **FraudRecord** and **IPQualityScore**.
- Injects live fraud scores, IP risk ratings, and email compromise alerts directly into the WHMCS client profile page.
- Direct **Abuse Reporting** form within the WHMCS admin card to submit reports to fraud services with one click.

### 4. Background Queue & Cron Automation

To ensure that client checkouts, registration, and profile edits remain fast, the module utilizes a background queue:

- **Asynchronous Execution:** Instead of waiting for external APIs during checkout, checks are enqueued and processed asynchronously by the background cron.
- **Scheduled Mass Re-checks:** Set the module to automatically re-screen your entire active client base on a daily, weekly, or monthly schedule.
- **Real-time Fallback:** If the background queue ever fails, the module falls back to real-time screening to guarantee that no screening is missed.

### 5. Verification (Whitelist) Workflow

Manage false positives easily with a structured verification system:

- Mark checked clients as **Verified** to bypass subsequent automated checks during orders or mass cron sweeps.
- **Admin Audit Trail:** The module records a snapshot of the verifying administrator (ID, username, email, time) and displays it inside the verification badges.
- **Automatic Reset:** If a verified client edits their profile, their verified status is automatically reset and they are re-queued for checking.

### 6. Interactive Admin Console

- **Dashboard Overview:** Live counter cards showing total checks, matching records, whitelist statistics, and sync states.
- **List Entries Browser:** Full-featured search and filtering tool to inspect exact names and raw entities mirrored from OpenSanctions.
- **Direct Entity Links:** All matching results link directly to the corresponding **OpenSanctions** entity profiles for rapid manual audit.
- **Database Schema Verification:** Built-in declarative schema validator checks and updates missing DB tables and columns non-destructively in one click.

- - - - - -

## System Requirements

<table id="bkmrk-requirement-minimum-"><thead><tr><th>Requirement</th><th>Minimum</th></tr></thead><tbody><tr><td>WHMCS</td><td>8.x or higher</td></tr><tr><td>PHP</td><td>7.4, 8.1, or 8.2</td></tr><tr><td>Remote API</td><td>trade.gov CSL API, FraudRecord, IPQualityScore (optional)</td></tr><tr><td>ionCube Loader</td><td>v13 or newer</td></tr></tbody></table>

- - - - - -

## Module Components

<table id="bkmrk-component-type-direc"><thead><tr><th>Component</th><th>Type</th><th>Directory</th></tr></thead><tbody><tr><td>Addon Module</td><td>`puq_sanctions_checker`</td><td>`modules/addons/puq_sanctions_checker/`</td></tr></tbody></table>

- - - - - -

## Important Links

- **Official Product Page:** [https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php)
- **Documentation Book:** [https://doc.puq.info/books/sanctions-checker-whmcs-addon](https://doc.puq.info/books/sanctions-checker-whmcs-addon)
- **GitHub Repository:** [https://github.com/puqcloud/WHMCS-Addon-PUQ-Sanctions-Checker](https://github.com/puqcloud/WHMCS-Addon-PUQ-Sanctions-Checker)
- **Technical Support:** [https://puqcloud.com/submitticket.php?step=2&amp;deptid=1](https://puqcloud.com/submitticket.php?step=2&deptid=1)

- - - - - -

## Screenshots

### Administrative Dashboard

![Dashboard](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-qeuustlx.png)

### Screening Results Audit

![Screening Results](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-gnkcrg9c.png)# Changelog

### PUQ Sanctions Checker module **[WHMCS](https://puqcloud.com/link.php?id=77)**

##### [Order now](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/) | [FAQ](https://faq.puqcloud.com/)

- - - - - -

## v1.0.0 — 11-07-2026

Initial release of the PUQ Sanctions Checker module for WHMCS, enabling automated screening of clients against international sanctions lists and fraud databases.

### Sanctions Screening Engine

Integrated US CSL API (combining 11 US lists) with fuzzy name matching, and local database mirrors for EU FSF and Canada DFATD-SEMA. Added country blocklists.

### Automated and Manual Triggers

Added automated background screening on client registration, profile updates, and checkouts. Integrated manual triggers directly on client profile page and the admin UI dashboard.

### Verification &amp; Fraud Check

Implemented false-positive verification workflow, ticket automation on match, and fraud check integration with FraudRecord and IPQualityScore.# Installation and update

Guide on how to install, update, and uninstall PUQ Sanctions Checker.

# WHMCS Module Installation and Update

### PUQ Sanctions Checker module **[WHMCS](https://puqcloud.com/link.php?id=77)**
##### [Order now](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/) | [Community](https://community.puqcloud.com/)

## System Requirements

| Requirement | Minimum          |
|-------------|------------------|
| WHMCS       | 8.x or higher |
| PHP         | 7.4, 8.1, or 8.2 |
| ionCube Loader | v13 or newer  |

> **Note:** The module is encrypted with ionCube. Ensure that the correct ionCube Loader version is active on your web server.

---

## Download

The module is distributed as a single ZIP archive. A separate build is published for each supported PHP major version.

All versions and historical builds are available in the index:
- [https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/)

### Direct "latest" downloads

#### PHP 8.2
```bash
wget https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/php82/PUQ_WHMCS-Sanctions-Checker-latest.zip
```

#### PHP 8.1
```bash
wget https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/php81/PUQ_WHMCS-Sanctions-Checker-latest.zip
```

#### PHP 7.4
```bash
wget https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/php74/PUQ_WHMCS-Sanctions-Checker-latest.zip
```

> Not sure which PHP version your WHMCS runs on? Check **Utilities > System > PHP Info** in the WHMCS admin area.

---

## Installation

### Step 1: Unzip the Archive
On your WHMCS server (or locally):
```bash
unzip PUQ_WHMCS-Sanctions-Checker-latest.zip
```

### Step 2: Copy the Module Files
Copy the extracted module directory directly to your WHMCS directory:

```bash
cp -r PUQ_WHMCS-Sanctions-Checker/puq_sanctions_checker /var/www/html/whmcs/modules/addons/
```

### Step 3: Activate and Configure the Addon Module
1. Log in to the WHMCS admin area.
2. Navigate to **System Settings > Addon Modules** (or **Setup > Addon Modules** in older WHMCS versions).
3. Find **PUQ Sanctions Checker** in the list and click **Activate**.
4. Click **Configure**, enter your **License Key**, and select the admin groups allowed to access the module.
5. Click **Save Changes**.

---

## File Structure

Structure of files after a successful installation:
```
whmcs/
└── modules/
    └── addons/
        └── puq_sanctions_checker/          # Addon files
```

---

## Update Procedure

To update the module to a newer version:
1. **Deactivate** the addon module in **Setup > Addon Modules** (System Settings > Addon Modules).
2. Make a backup of your WHMCS files and database.
3. Download the latest version for your PHP version.
4. Extract the ZIP and overwrite the existing files in the `modules/` directories.
5. **Reactivate** the addon module in **Setup > Addon Modules** (this will trigger database migrations). All settings and client data are safe during this process.

<!-- sync:166ff333a2f482f0 -->

# Activation and permissions

Configuration of WHMCS access controls and module licensing.

# Activation and permissions

### PUQ Sanctions Checker module **[WHMCS](https://puqcloud.com/link.php?id=77)**
##### [Order now](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/) | [Community](https://community.puqcloud.com/)

To activate the module and set up permissions, follow these steps:

1. Log in to your WHMCS Admin Area.
2. Navigate to **System Settings > Addon Modules** (or **Setup > Addon Modules** in older WHMCS versions).
3. Locate **PUQ Sanctions Checker** in the list and click **Activate**.
4. Once activated, click **Configure** next to the module name.
5. In the configuration panel:
   - Enter your **License key** (provided upon purchase).
   - Under **Access Control**, select the administrative role groups (e.g., Full Administrator, Support) that are permitted to access and manage this module.
6. Click **Save Changes**.

![Addon activation — license key and access control](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-c3ndibkb.png)


<!-- sync:211025a67f6c9197 -->

# Admin area

Using the admin interface and managing screening results, settings, and logs.

# Dashboard

### PUQ Sanctions Checker module **[WHMCS](https://puqcloud.com/link.php?id=77)**
##### [Order now](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/) | [Community](https://community.puqcloud.com/)


**Addons → Sanctions Checker → Home** — the operational overview of the module.

![Dashboard — statistics, sanctions sources, mass check, and database tools](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-qpql3fzh.png)

## Statistics cards

| Card | Meaning |
| --- | --- |
| Clients total | All clients in WHMCS. |
| Clients checked | Clients that have at least one screening result. |
| Matches | Clients currently matching sanctions lists — the red alert on top links straight to the filtered list. |
| Clean | Clients checked with no findings. |
| Entries: Canada / EU | Number of sanctions list entries in the local database. |

## Sanctions sources panel

Shows the time of the last list synchronization. **Sync sanctions lists now** downloads the enabled OpenSanctions mirrors immediately (the daily cron does the same automatically).

## Last mass check panel

Shows the last mass check time and the number of checks **pending in the queue**. **Check all clients now** starts a mass check:

- with **Queue the mass check** enabled (default) the clients are added to the queue and the cron processes them within minutes;
- with the queue disabled the check runs in your browser in batches with a progress bar.

## Database panel

**Check database tables** verifies all module tables and creates any missing tables or columns (useful after a module update). It is non-destructive — nothing is ever dropped — and displays a per-table report (`created` / `altered` / `unchanged`).

<!-- sync:ef6e8f096a826eea -->

# Screening results

### PUQ Sanctions Checker module **[WHMCS](https://puqcloud.com/link.php?id=77)**
##### [Order now](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/) | [Community](https://community.puqcloud.com/)


**Addons → Sanctions Checker → Clients** — every client that has been screened, with the full match details.

![Screening results — filters, match details with OpenSanctions links, tickets, verification](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-65j0v28g.png)

## Filters

**All / Matches / Clean / Verified** — one click switches the view. *Matches* is where the daily review happens; *Verified* lists clients an admin has marked as reviewed false-positives.

## Columns

| Column | Meaning |
| --- | --- |
| Client | Name and company, linked to the client profile. |
| Status | `MATCH` (red) / `CLEAN` (green); a green `VERIFIED` badge appears next to it for verified clients (hover it to see who verified and when). |
| Score | The highest match percent (see [How the matching engine works](../06-automation-and-cron/01-matching-engine.md)). |
| Matches | Every matched list entry: source (`ca_dfatd`, `eu_fsf`, `csl:…`, `blocked_country`), matched name, score. The external-link icon opens the **OpenSanctions entity profile** so you can see exactly who the client was compared with. |
| Ticket | The support ticket opened for this match. |
| Checked At | Time of the last check. |

## Row actions

- **Recheck** — re-screens the client immediately (always real time, never queued).
- **Mark as Verified** — appears on matched clients; see [Client profile panel & verification](03-client-profile-panel.md).
- **Remove Verification** — appears on verified clients.

<!-- sync:5b842628f2572e91 -->

# Client profile panel & verification

### PUQ Sanctions Checker module **[WHMCS](https://puqcloud.com/link.php?id=77)**
##### [Order now](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/) | [Community](https://community.puqcloud.com/)


On every admin client page (Summary, Profile, Services, Invoices, …) the module injects a compact panel with the current screening state. Everything on it works via AJAX — no page reloads.

## When the client matches

![Client profile — MATCH badge with the best match, Check Now, Mark as Verified, View All Data](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-vauq9qo1.png)

The panel shows the `MATCH` badge with the number of matches, the **best-scoring matched name with its percent**, a link to the opened ticket, and the check time.

- **Check Now** — re-screens the client immediately; when matches are found, the details modal opens automatically.
- **Mark as Verified** — the false-positive workflow (see below).
- **View All Data** — the full details modal.

## View All Data

![View All Data — status, score, and every match with an OpenSanctions link](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-cxvlfoch.png)

Each local-list match links to its **OpenSanctions entity profile** (aliases, birth dates, sanction programs) — open it to visually confirm whether your client is really the listed person. When Fraud Check is enabled, the same modal also shows the raw FraudRecord / IPQualityScore data.

## Verification (false positives)

A clean client can share a surname with a listed person and would be flagged on every re-check. After reviewing the details, click **Mark as Verified**:

![Client profile — VERIFIED badge next to the match state](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-exqr0odu.png)

A verified client:

- is **skipped by all automatic checks** — cron, mass check, registration, and order triggers;
- gets **no tickets, status changes, or group moves**, even from a manual re-check;
- can still be re-checked manually at any time;
- **loses the verification automatically when the client changes profile data** — the check then runs again in full.

The module records **who** verified the client — first name, last name, login, and email of the admin are stored as a snapshot (not a reference), so the information survives even if the admin account is later deleted:

![View All Data on a verified client — who verified, when, and what it means](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-epkkr2el.png)

**Remove Verification** puts the client back under automatic screening. Every verify/unverify action is written to the module log and the WHMCS activity log.

## Fraud Check on the panel

With Fraud Check enabled the same panel shows the FraudRecord score, IP fraud score, and email leak status with their own **Fraud Check Now** and **Send Report** buttons — see [Configuration → Fraud Check](09-config-fraud-check.md).

<!-- sync:dc1761d78b86b68e -->

# List entries browser

### PUQ Sanctions Checker module **[WHMCS](https://puqcloud.com/link.php?id=77)**
##### [Order now](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/) | [Community](https://community.puqcloud.com/)


**Addons → Sanctions Checker → List Entries** — everything the module downloaded from the OpenSanctions mirrors, so you can verify what exactly your clients are compared against.

![List Entries — live search, source filter, pagination](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-zrpzorie.png)

- **Search** — live search by name, alias, country code, or entity ID (400 ms debounce).
- **Source filter** — all sources / Canada (DFATD-SEMA) / EU (FSF); the counter on the right shows the total.
- **Columns** — source badge (CA/EU), entity type (Person / Organization / LegalEntity), primary name, aliases (hover for the full list), birth date, countries, and the import time.
- 50 entries per page with Previous/Next paging.

The data refreshes automatically with the daily cron; **Sync sanctions lists now** on the Home page forces an immediate refresh.

<!-- sync:8aa9fc84baa363ee -->

# Log

### PUQ Sanctions Checker module **[WHMCS](https://puqcloud.com/link.php?id=77)**
##### [Order now](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/) | [Community](https://community.puqcloud.com/)


**Addons → Sanctions Checker → Log** — the audit trail of everything the module does (last 500 entries).

![Log — checks, tickets, verification, synchronization, queue](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-iswcgfwv.png)

| Event | Meaning |
| --- | --- |
| `sanctions_check` | A client was screened: context (manual / register / edit / order / mass / cron), result, number of matches, max score. |
| `ticket_opened` | A support ticket was created for a match. |
| `ticket_skipped` | No ticket was created — the reason is spelled out (an earlier ticket is still open, or no department is configured). |
| `ticket_error` | The ticket API call failed — the full response is logged. |
| `whitelisted` / `whitelist_removed` / `whitelist_reset` | Verification set by an admin / removed by an admin / dropped automatically because the client changed profile data. |
| `client_updated` | Status change / group move applied on a match. |
| `list_sync` | Sanctions lists downloaded (per-source entry counts and errors). |
| `mass_check` | A mass check ran or was queued. |
| `queue_processed` | A cron tick processed a portion of the check queue. |
| `check_error` | A queued or batched check failed for one client. |
| `configuration_saved` / `schema_check` | Settings saved / database schema verified. |

Client numbers link to the client profile.

<!-- sync:b5a2da427b6eb6f9 -->

# Configuration — Sanctions sources

### PUQ Sanctions Checker module **[WHMCS](https://puqcloud.com/link.php?id=77)**
##### [Order now](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/) | [Community](https://community.puqcloud.com/)


**Addons → Sanctions Checker → Configuration → Sanctions sources.** All settings are saved with the green **Save Changes** button; only the license key lives in Setup → Addon Modules.

![Sanctions sources tab — local lists, matching engine, CSL API, blocked countries](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-tqxo3shy.png)

## Local lists (OpenSanctions mirrors)

![Local lists — Canada DFATD-SEMA and EU FSF toggles](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-swhdvwff.png)

Official government sanctions lists mirrored by the [OpenSanctions](https://www.opensanctions.org/) project as clean machine-readable files (~2 MB each). No registration or API key required. The files are imported into your database and matching runs **locally** — no client data leaves your server. Synchronized daily by cron.

## Matching engine

![Matching engine — thresholds for the three matching methods](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-prz4xgsf.png)

| Setting | Default | Description |
| --- | --- | --- |
| Full name match threshold | 85% | Similarity of the whole name required to report a match. |
| Enable trigram matching + threshold | on / 65% | 3-letter-chunk comparison, catches typos and letter swaps. |
| Trigram minimum name length | 6 | Trigrams run only when both names have at least this many letters — short names would match randomly. |
| Enable per-word matching + minimum words | on / 1 | Only the **surname** or a **company word** can trigger a match; a first-name-only hit never flags. Minimum 1 flags surname-only matches (with a lower score); 2 requires first + last name. |
| Word similarity threshold | 85% | How similar two words must be to count as a pair (catches Ivanov / Ivanoff). |

The methods are explained in detail in [How the matching engine works](../06-automation-and-cron/01-matching-engine.md).

## US Consolidated Screening List API

![CSL API — key, endpoint, minimum score](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-flgqv9pq.png)

Real-time fuzzy search against 11 US lists (OFAC SDN, BIS Entity List, State Department). Get a free API key at the [ITA API portal](https://api.trade.gov/apps/store/site/pages/sign-up.html); results below **CSL minimum match score** (default 90) are ignored. Client names are sent to trade.gov over HTTPS.

## Blocked countries

![Blocked countries — comma-separated ISO-2 codes](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-a9jjhfeg.png)

Comma-separated ISO-2 country codes (e.g. `RU,BY,IR,KP,SY,CU`). The country from the client profile is compared against this list; a match is reported with score 100.

<!-- sync:4c2ab8a818987684 -->

# Configuration — Check triggers & queue

### PUQ Sanctions Checker module **[WHMCS](https://puqcloud.com/link.php?id=77)**
##### [Order now](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/) | [Community](https://community.puqcloud.com/)


**Addons → Sanctions Checker → Configuration → Check triggers** — when checks run automatically.

![Check triggers tab — triggers, queue, periodic mass check](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-6fqkyfob.png)

## Check triggers

![Triggers — registration, profile update, checkout, and the queue toggle](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-oik0vnz5.png)

| Setting | Description |
| --- | --- |
| Check on client registration | Screen every new client (`ClientAdd`). |
| Check on client profile update | Re-screen when the client changes profile data (`ClientEdit`). This also drops the *Verified* flag — see [verification](03-client-profile-panel.md). |
| Check on order checkout | Screen on every order checkout. |
| **Run trigger checks on the next cron (queue)** | Applies to the three triggers above ONLY. Instead of checking during the client's request — which can be slow and cause timeouts when external APIs are enabled — the client is added to the queue and checked by the cron within a few minutes. **Manual checks always run in real time.** |

## Periodic mass check

![Periodic mass check — frequency, scope, queue, batch size](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-ljf3nhxl.png)

| Setting | Default | Description |
| --- | --- | --- |
| Periodic mass check (cron) | Disabled | Disabled / Daily / Weekly / Monthly re-check of the client base. Sanctions lists change constantly — a weekly or monthly re-check is recommended. |
| Clients to check in mass check | Active only | Active clients only, or all clients. |
| Queue the mass check | **on** | The mass check (Home-page button and the schedule) adds clients to the queue; the cron drains it in portions. Recommended for large client bases. |
| Queue items processed per cron run | 50 | Portion size per cron tick (~5 minutes). Lower it when the CSL API is enabled. |

Verified clients are excluded from the mass check automatically. How the queue works internally is described in [Cron automation & check queue](../06-automation-and-cron/02-cron-and-queue.md).

<!-- sync:bb418cbbaf4de598 -->

# Configuration — Actions on match

### PUQ Sanctions Checker module **[WHMCS](https://puqcloud.com/link.php?id=77)**
##### [Order now](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/) | [Community](https://community.puqcloud.com/)


**Addons → Sanctions Checker → Configuration → Actions on match** — what happens when a check finds a match.

![Actions on match tab — ticket settings and client actions](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-nxlucsla.png)

## Support ticket

![Ticket settings — department, subject, message with merge fields](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-9symnfc5.png)

| Setting | Description |
| --- | --- |
| Open a support ticket | Master toggle. **One ticket per client**: while a sanctions ticket is open, repeated checks do not create duplicates. If the ticket was closed and the client still matches later, a new ticket is opened. |
| Support department | Where the ticket is created. |
| Ticket subject / message | Your own templates with merge fields: `{client_id}`, `{client_name}`, `{client_company}`, `{client_email}`, `{client_country}`, `{matches}`, `{date}`. |

A real ticket produced by the module — `{matches}` expands into the full list with sources, scores, and the method that matched:

![Sanctions ticket example](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-v6nuzatt.png)

## Client actions

![Client actions — status change and group move](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-0qlaxzpr.png)

| Setting | Description |
| --- | --- |
| Set client status | Optionally set the client to Active / Inactive / Closed on a match. Leave empty to keep the status unchanged. |
| Move client to group | Optionally move the client into a chosen client group (handy for a "Sanctions review" group). Leave empty to keep the group. |

Both actions are applied on every check that finds a match — but **never** for [verified](03-client-profile-panel.md) clients. Every action is written to the log (`client_updated`, `ticket_opened`, `ticket_skipped` with the reason).

<!-- sync:a587934c7d54bb54 -->

# Configuration — Fraud Check

### PUQ Sanctions Checker module **[WHMCS](https://puqcloud.com/link.php?id=77)**
##### [Order now](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/) | [Community](https://community.puqcloud.com/)


**Addons → Sanctions Checker → Configuration → Fraud Check** — the built-in fraud screening via FraudRecord and IPQualityScore.

![Fraud Check tab — services, master toggle, triggers](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-8tqeganr.png)

## Services

![FraudRecord and IPQualityScore — registration links and API keys](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-ilsyj0ik.png)

- **FraudRecord** ([register free](https://fraudrecord.com/register)) — a shared database of abuse reports from hosting providers. Client data is **hashed locally** before it is sent, so no plain-text personal data leaves your server. Create a reporter profile to get an API key.
- **IPQualityScore** ([create account](https://www.ipqualityscore.com/create-account)) — scores the client's IP for proxy/VPN/fraud risk and checks whether the email address appears in leaked databases. The free plan includes monthly lookup credits.

## Master toggle and triggers

![Fraud check master toggle and its own triggers](https://doc.puq.info/uploads/images/gallery/2026-07/embedded-image-zqptyrrg.png)

| Setting | Description |
| --- | --- |
| Fraud check enabled | Master toggle; at least one service with an API key must be enabled. |
| Fraud check on registration / profile update / order checkout | The same trigger events as the sanctions checks, controlled separately. With the [check queue](07-config-check-triggers.md) enabled for triggers, fraud checks are queued too. |

## Where you see the results

The [client profile panel](03-client-profile-panel.md) shows `Fraudrecord: 0-0-0 | Fraud IP: 0% | Fraud Email: NO` badges (red = findings), a **Fraud Check Now** button, and **Send Report** — a form (fraud type, level 1–10, free text) that submits an abuse report to FraudRecord and/or IPQualityScore. Raw API responses are available in the **View All Data** modal.

<!-- sync:a6b72a4adb12f588 -->

# Automation and cron

How the automatic screening engine and scheduled tasks work.

# How the matching engine works

### PUQ Sanctions Checker module **[WHMCS](https://puqcloud.com/link.php?id=77)**
##### [Order now](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/) | [Community](https://community.puqcloud.com/)


For every client the module screens two name candidates against the local lists: `firstname lastname` and `companyname` (plus the profile country against the [blocked-countries list](../05-admin-area/06-config-sanctions-sources.md)).

## Normalization

Both the client name and every list entry name/alias go through the same pipeline: lowercase → Cyrillic transliterated to Latin (`Иванов` → `ivanov`) → remaining accents transliterated to ASCII (`Müller` → `muller`) → everything except letters/digits/spaces removed → multiple spaces collapsed.

## The three methods

Each pair is scored by up to three configurable methods ([Configuration → Sanctions sources → Matching engine](../05-admin-area/06-config-sanctions-sources.md)); the best score wins and the method that produced it is shown in the match details.

### 1. Full name (`local_match_threshold`, default 85%)

PHP `similar_text` over the whole normalized strings: `2 × common_characters / (len1 + len2) × 100`. Repeated with alphabetically sorted words, higher of the two wins, so `Ivan Ivanov` = `Ivanov Ivan` = 100%. Example: `dmitry ivanov` vs `dmitrii ivanov` ≈ 89%.

### 2. Trigrams (default on / 65% / min length 6)

Both names are cut into 3-letter chunks sliding from start to end (` iv`, `iva`, `van`, `ano`, `nov`, …) and the share of common chunks is computed (Dice: `2 × common / (n1 + n2) × 100`). Very tolerant to typos and letter swaps: `Vladimir` vs `Vladimr` ≈ 81%. The method runs only when **both names have at least `trigram_min_length` letters** (spaces not counted) — short names like `Li Wei` produce so few chunks that unrelated names would cross the threshold by coincidence.

### 3. Words (default on / minimum 1 / word similarity 85%)

Every client word is matched to the closest entry word (words shorter than 3 letters and generic company suffixes like LLC/Ltd/GmbH are ignored); a pair counts when the two words are ≥ `word_similarity_threshold` similar (`Ivanov`/`Ivanoff` counts). The entry is reported when at least `word_match_min_words` pairs matched **and at least one matched word is the client SURNAME or a company word — a first-name-only match never flags the client**. The score is scaled by the fraction of client words that matched: a surname-only hit on "Ivan Ivanov" scores ~50%, a full-name hit ~100%.

With the default minimum of 1, clients whose surname (or one company word) matches a listed person are flagged **for review** with a proportionally lower score — the admin inspects the match (each one links to the OpenSanctions entity profile) and either acts or [marks the client as Verified](../05-admin-area/03-client-profile-panel.md).

## Reference behaviour (default settings)

| Client vs list entry | Result |
| --- | --- |
| `Vladimr Putin` vs `Vladimir Putin` (typo) | full 96% |
| `Дмитрий Петров` vs `Dmitriy Petrov` (Cyrillic) | full 93% |
| `Dmytro Kravchenko` vs `Denis Borisovich KRAVCHENKO` (surname only) | words 1/2, score 50% |
| `Denis Petrenko` vs `Denis Borisovich KRAVCHENKO` (first name only) | **no match** |
| `Roskosmos LLC` vs `State Corporation Roskosmos` (company word) | words 1/1, score 100% |
| `Alpha Trading LLC` vs `Bravo Trading Limited` (suffixes only) | **no match** |
| Unrelated names | no match |

## The US CSL API

When enabled, each name candidate is sent to the trade.gov API with `fuzzy_name=true`. The government's own fuzzy algorithm handles typos and transliteration variants and returns a match score; results below **CSL minimum match score** are dropped.

**Important:** a match is a signal for manual review, not proof. Fuzzy matching by name always produces some false positives — that is why the ticket is the primary action and the [verification workflow](../05-admin-area/03-client-profile-panel.md) exists.

<!-- sync:80b040edeb918489 -->

# Cron automation & check queue

### PUQ Sanctions Checker module **[WHMCS](https://puqcloud.com/link.php?id=77)**
##### [Order now](https://puqcloud.com/whmcs-addon-puq-sanctions-checker.php) | [Download](https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/) | [Community](https://community.puqcloud.com/)


The module uses the standard WHMCS cron. No extra cron entries are needed:

- `DailyCronJob` — list synchronization, mass-check scheduling, queue housekeeping;
- `AfterCronJob` (every cron tick, normally ~5 minutes) — **check queue processing**.

## The check queue

Checks can be slow: the CSL API is an external HTTPS call per name, FraudRecord hashes every field 32 000 times. Running that inline during client registration or checkout can cause visible delays and timeouts. The queue solves this:

| Setting | Default | Effect |
| --- | --- | --- |
| Run trigger checks on the next cron (queue) | **off** | Registration / profile update / order checkout only **add the client to the queue** (instant) and the cron performs the check within ~5 minutes. Off = checks run inline as before. |
| Queue the mass check (process on cron) | **on** | The "Check all clients now" button and the scheduled mass check put clients into the queue; the cron drains it in portions. Off = the button runs realtime AJAX batches with a progress bar. |
| Queue items processed per cron run | 50 | Portion size per cron tick. Lower it when the CSL API is enabled. |

**Manual checks always run in real time** — the Check Now button on the client card and Recheck on the Clients page never use the queue.

The queue lives in `puq_sanctions_checker_queue` (client, type sanctions/fraud, context, status pending → processing → done/error). The Home page shows the number of pending items; every processed portion is logged (`queue_processed`), failures per client are logged as `check_error`. Finished rows are purged after 7 days. If the queue table is unavailable, trigger checks automatically fall back to real-time so registration never breaks.

## What runs daily

1. **Sanctions lists synchronization** — the enabled OpenSanctions mirrors (EU FSF, Canada DFATD-SEMA) are downloaded and re-imported into the local database. The files are ~2 MB each and the URLs are static, so this is fast and reliable.

2. **Periodic mass check** — when **Periodic mass check (cron)** is set to Daily, Weekly, or Monthly, the module re-screens clients (Active only or all, per the **Clients to check in mass check** setting) once per period — via the queue by default. The last run timestamp is shown on the Home page.

## Notes

- Tickets are deduplicated, so a weekly mass check does not spam the helpdesk: a client with an already-open sanctions ticket does not get a second one.
- All cron activity is written to the module **Log** page (`list_sync`, `mass_check`, `queue_processed` events).

## Manual equivalents

Everything the cron does can be triggered from the **Home** page: **Sync sanctions lists now** and **Check all clients now** (queued by default; with the queue disabled — realtime batches with a progress bar).

<!-- sync:74b37af642f03cfd -->