Sanctions Checker WHMCS Addon Description Changelog Installation and update Guide on how to install, update, and uninstall PUQ Sanctions Checker. 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: https://download.puqcloud.com/WHMCS/addons/PUQ_WHMCS-Sanctions-Checker/ 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 Log in to the WHMCS admin area. Navigate to System Settings > Addon Modules (or Setup > Addon Modules in older WHMCS versions). Find PUQ Sanctions Checker in the list and click Activate. Click Configure, enter your License Key, and select the admin groups allowed to access the module. 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: Deactivate the addon module in Setup > Addon Modules (System Settings > Addon Modules). Make a backup of your WHMCS files and database. Download the latest version for your PHP version. Extract the ZIP and overwrite the existing files in the modules/ directories. 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 PUQ Sanctions Checker module WHMCS Order now | Download | Community To activate the module and set up permissions, follow these steps: Log in to your WHMCS Admin Area. Navigate to System Settings > Addon Modules (or Setup > Addon Modules in older WHMCS versions). Locate PUQ Sanctions Checker in the list and click Activate. Once activated, click Configure next to the module name. 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. Click Save Changes. Admin area Using the admin interface and managing screening results, settings, and logs. Dashboard PUQ Sanctions Checker module WHMCS Order now | Download | Community Addons → Sanctions Checker → Home — the operational overview of the module. 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). 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. 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 Recheck — re-screens the client immediately (always real time, never queued). Mark as Verified — appears on matched clients; see Client profile panel & verification. Remove Verification — appears on verified clients. 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 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 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: 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: 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. 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. 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. 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). 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. 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. Local lists (OpenSanctions mirrors) 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 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 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 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. 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 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 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. 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. Support ticket 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: Client actions 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). 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. Services FraudRecord (register free) — 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) — 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 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. 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. 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: 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 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. 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).