PUQ Mautic

Sanctions Checker WHMCS Addon

WHMCS addon module that screens clients against international sanctions lists (US CSL via trade.gov API, EU FSF and Canada DFATD-SEMA via OpenSanctions mirrors, blocked countries) with automatic checks on registration, profile update, checkout, and cron schedule. Opens deduplicated support tickets on match, optionally changes client status and group. Includes FraudRecord and IPQualityScore fraud checks with reporting.

Description

PUQ Sanctions Checker module WHMCS

Order now | Download | FAQ/Community

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:

2. Multi-Source Sanctions Screening

Clients are matched against multiple authoritative databases simultaneously:

3. Integrated Fraud Check (FraudRecord & IPQualityScore)

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

4. Background Queue & Cron Automation

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

5. Verification (Whitelist) Workflow

Manage false positives easily with a structured verification system:

6. Interactive Admin Console

System Requirements

Requirement Minimum
WHMCS 8.x or higher
PHP 7.4, 8.1, or 8.2
Remote API trade.gov CSL API, FraudRecord, IPQualityScore (optional)
ionCube Loader v13 or newer

Module Components

Component Type Directory
Addon Module puq_sanctions_checker modules/addons/puq_sanctions_checker/

Screenshots

Administrative Dashboard

Dashboard

Screening Results Audit

Screening Results

Changelog

PUQ Sanctions Checker module WHMCS

Order now | Download | FAQ

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 & 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.

Installation and update

WHMCS Module Installation and Update

PUQ Sanctions Checker module WHMCS

Order now | Download | Community

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:

Direct "latest" downloads

PHP 8.2

wget https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/php82/PUQ_WHMCS-Sanctions-Checker-latest.zip

PHP 8.1

wget https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/php81/PUQ_WHMCS-Sanctions-Checker-latest.zip

PHP 7.4

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):

unzip PUQ_WHMCS-Sanctions-Checker-latest.zip

Step 2: Copy the Module Files

Copy the extracted module directory directly to your WHMCS directory:

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.

Activation and permissions

Configuration of WHMCS access controls and module licensing.

Activation and permissions

Activation and permissions

PUQ Sanctions Checker module WHMCS

Order now | Download | Community

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

Admin area

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

Admin area

Dashboard

PUQ Sanctions Checker module WHMCS

Order now | Download | Community

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

Dashboard — statistics, sanctions sources, mass check, and database tools

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:

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).

Admin area

Screening results

PUQ Sanctions Checker module WHMCS

Order now | Download | Community

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

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).
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

Admin area

Client profile panel & verification

PUQ Sanctions Checker module WHMCS

Order now | Download | Community

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

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.

View All Data

View All Data — status, score, and every match with an OpenSanctions link

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

A verified client:

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

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.

Admin area

List entries browser

PUQ Sanctions Checker module WHMCS

Order now | Download | Community

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

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

Admin area

Log

PUQ Sanctions Checker module WHMCS

Order now | Download | Community

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

Log — checks, tickets, verification, synchronization, queue

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.

Admin area

Configuration — Sanctions sources

PUQ Sanctions Checker module WHMCS

Order now | Download | Community

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

Local lists (OpenSanctions mirrors)

Local lists — Canada DFATD-SEMA and EU FSF toggles

Official government sanctions lists mirrored by the OpenSanctions 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

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.

US Consolidated Screening List API

CSL API — key, endpoint, minimum score

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; 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

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.

Admin area

Configuration — Check triggers & queue

PUQ Sanctions Checker module WHMCS

Order now | Download | Community

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

Check triggers tab — triggers, queue, periodic mass check

Check triggers

Triggers — registration, profile update, checkout, and the queue toggle

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.
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

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.

Admin area

Configuration — Actions on match

PUQ Sanctions Checker module WHMCS

Order now | Download | Community

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

Actions on match tab — ticket settings and client actions

Support ticket

Ticket settings — department, subject, message with merge fields

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

Client actions

Client actions — status change and group move

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 clients. Every action is written to the log (client_updated, ticket_opened, ticket_skipped with the reason).

Admin area

Configuration — Fraud Check

PUQ Sanctions Checker module WHMCS

Order now | Download | Community

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

Fraud Check tab — services, master toggle, triggers

Services

FraudRecord and IPQualityScore — registration links and API keys

Master toggle and triggers

Fraud check master toggle and its own triggers

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 enabled for triggers, fraud checks are queued too.

Where you see the results

The client profile panel 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.

Automation and cron

How the automatic screening engine and scheduled tasks work.

Automation and cron

How the matching engine works

PUQ Sanctions Checker module WHMCS

Order now | Download | Community

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).

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); 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.

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 exists.

Automation and cron

Cron automation & check queue

PUQ Sanctions Checker module WHMCS

Order now | Download | Community

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

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

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).