Version 1.8.0 · For WHMCS administrators and Arahoster staff

This guide covers eKYC Guard from download to a working setup. It explains how the gate decides who must verify and what every settings tab does, and it ends with upgrading and troubleshooting. If something here does not match what you see in your WHMCS, contact us (see Support).

Contents

• 1. Overview
• 2. Requirements
• 3. Buy, download & licence
• 4. Installation
• 5. First-time setup (15 minutes)
• 6. How it works
• 7. Verification providers
• 8. Fraud checks, smart triggers & sensitive actions
• 9. Daily work: reviewing, alerts & statistics
• 10. Settings reference
• 11. Upgrading
• 12. Troubleshooting
• 13. Support

1. Overview

What it is

eKYC Guard is a WHMCS addon module that holds services and domains until the customer has verified their identity. The customer verifies with a provider of your choice (Didit, Stripe Identity, Sumsub, Onfido, Persona, Shufti Pro or DigiLocker), or by uploading documents for your team to review. When they pass, everything that was held is provisioned automatically.

Everything runs inside your own WHMCS:

• Data is kept in your WHMCS database, in tables starting with mod_ekycguard_.
• Identity documents are encrypted and stored in a private folder outside the web root.
• Background work runs from the normal WHMCS cron.

Safety-first defaults

Installing eKYC Guard changes nothing for your customers until you decide otherwise:

• The gate itself is off until you tick Block provisioning until verified.
• Every automation that can hurt a customer is off: reminders, suspend, terminate and account disable. Preview impact shows what they would do before you switch them on.
• Every 1.8.0 feature is off: fraud checks, smart triggers, sensitive actions, alerts and the phone hand-off. Each has its own switch and options.
• If the licence is missing or invalid, the module fails open: enforcement and the daily run stop, and new orders provision normally. Orders that were already held stay Pending until you accept them or the customer verifies.

2. Requirements

sodium: document encryption at rest is on by default and needs the sodium extension. While encryption is on and sodium is missing, document uploads are refused (a file is never stored unencrypted) and the Settings page shows a warning. Ask your host to enable sodium (in cPanel: Select PHP Version → Extensions → sodium).

3. Buy, download & licence

1. Order eKYC Guard in our store at me.arahoster.com (Store → Arahoster Marketplace). It is $3.99 per month, or pay yearly and save 37%. Every feature is included.
2. After payment, open Services → My Services → eKYC Guard in the client area. Your licence key is shown there, together with the download.
3. Download the zip. Inside you'll find:

eKYC-Guard-v1.8.0/
├── INSTALL.txt
├── LICENSE.txt
├── README.txt
├── CHANGELOG.txt
└── modules/addons/ekycguard/      ← this is what you upload

Your licence is bound to your WHMCS domain the first time it is checked. The module keeps a signed local copy of the result, so it carries on working through short outages of our licence server.

4. Installation

Step 1 — Upload the files

Upload the modules folder from the zip into your WHMCS root, so that the module ends up at:

<your-whmcs>/modules/addons/ekycguard/

Merge the folder with your existing modules folder. Do not replace that folder.

Step 2 — Activate the module

1. In the WHMCS admin area open Configuration (spanner icon) → System Settings → Addon Modules.
2. Find eKYC Guard and click Activate.
3. Click Configure, tick the admin role groups that should use the module (at least Full Administrator), and click Save Changes.

Activation creates the module tables, installs the customer email templates (English, Arabic and Norwegian) and creates the document encryption key. It also chooses a private storage folder outside the web root.

Step 3 — Enter the licence key

Open Addons → eKYC Guard → Settings → Licence, paste your key and click Save changes. The tab shows the status, your plan and the expiry date. Re-check licence now forces a fresh check.

5. First-time setup (15 minutes)

Work through these tabs in Addons → eKYC Guard → Settings. Each setting has a short explanation underneath it.

1. Providers — turn on at least one method:
   • Manual upload: no account needed. Customers upload their ID, and your team approves or rejects it.
   • A provider (for example Didit): paste the keys from the provider's dashboard. Copy the Webhook URL shown on the panel (Copy button) into the provider's dashboard, then click Test connection.
2. Enforcement & scope:
   • Choose which clients, which products and which TLDs need KYC. By default that is everyone and everything; narrow it here if you like.
   • Pick the Client-area gating: off, Banner only (the default), or Restrict ordering. Restrict ordering sends unverified customers to the verification page when they try to order, check out or upgrade.
   • Tick Block provisioning until verified. This switches the gate on.
3. Client experience — keep Require consent checkbox on (your GDPR lawful basis). Optionally set the page language, intro text and banner text.
4. Data & privacy — check that the storage folder is outside the web root. The tab says so in green. Optionally set Delete documents after (days).
5. Automation — when you are ready, switch on reminders, then press Preview impact before switching on suspend, terminate or disable.

Check that it works

1. Place a test order as a test client for a product that is in scope.
2. The order is held. In Addons → eKYC Guard you see the client as Pending.
3. Open the client area as that client and go to Verification: you see the methods you enabled. Complete one (or upload test documents).
4. Pay the test invoice and approve the verification. With Auto-provision on verify switched on, the held order is accepted and the service is created.

6. How it works

The gate

eKYC Guard hooks into the points where WHMCS creates something:

Admin override: if Let admins override the gate is on (the default), an administrator who clicks Create, Accept Order or Register in the admin area can still go ahead. Every override is logged, and services created this way are never auto-suspended by eKYC Guard.

When the customer passes, eKYC Guard releases what it held:

• Paid orders are accepted, and services are created with their normal welcome email. This needs Auto-provision on verify (off by default).
• Unpaid orders provision normally once the invoice is paid.
• Anything else is listed on the dashboard for an admin.

Who has to verify (scope)

A customer needs KYC only if every active rule says so:

• Client scope — all clients, only listed clients or groups, or everyone except listed ones
• Product scope and TLD scope — the same idea for products and domain extensions
• Country rules — let listed countries skip KYC, or require it only for listed countries. The country is decided from the IP location and the billing country (both, by default). A VPN, proxy or unknown location never counts as a match.
• Smart triggers — only orders that meet your conditions (see section 8)
• Risk-based KYC — a risky IP (VPN, Tor, proxy, or a high risk score from ProxyCheck.io or IPQualityScore) can make KYC required even for clients and products that are otherwise out of scope (Override mode). Strict only mode requires KYC only for risky IPs.

When country rules or smart triggers are active, the customer's verification page in the admin area shows the decision and the reason.

The daily run (cron)

Once a day the WHMCS cron runs eKYC Guard's daily tasks (skipped while the licence is invalid):

1. For Didit, Stripe Identity, Persona and Onfido, it asks the provider about sessions that have been idle for over an hour, in case their webhook was missed.
2. It deletes documents past your retention period and rejected records past their limit, if you set these.
3. It expires verifications that are due for periodic re-verification and invites those customers again.
4. For each customer who still needs to verify:
   • it sends reminder 1 and reminder 2 on the days you set (if reminders are on);
   • after the grace period, and only for the actions you switched on, it suspends in-scope services, terminates services that eKYC Guard itself suspended at least Terminate after (days) earlier (default 14), and sets the account to Inactive.

By default only services and domains ordered after enforcement started are affected. Old services are left alone unless you tick Also enforce on pre-existing services. With a grace period of 0, nothing is suspended, terminated or disabled.

Where data lives

• Verification records, logs and settings are in your WHMCS database.
• Documents are encrypted (libsodium) and stored outside the web root. Admins open them through a protected download link, and every access is logged.
• Document numbers are not stored by the fraud checks: only a keyed fingerprint and the last three characters are kept.
• When a client is deleted in WHMCS, their verification data is removed as well.

7. Verification providers

Each provider has its own panel on Settings → Providers, with an Enable switch, the keys and a Test connection button. Webhook providers also show a Webhook URL to copy into their dashboard. It looks like this:

https://your-whmcs/modules/addons/ekycguard/webhook.php?provider=didit

You can enable several providers; the customer chooses. Decisions arrive by signed webhook (checked before anything changes). For Didit, Stripe Identity, Persona and Onfido, the daily run also asks the provider about sessions whose webhook was missed.

AML screening (Settings → AML screening) checks verified names against sanctions and PEP lists through OpenSanctions. A possible match goes to manual review instead of being approved.

8. Fraud checks, smart triggers & sensitive actions

All of these are new in 1.8.0, and each one is off until you switch it on.

Fraud checks (Settings → Fraud checks)

Each check has its own action:

• Flag only: a note on the verification
• Manual review: an automated approval is held for a person
• Reject: with your own message to the customer

Your own manual approvals are never overridden.

Same person on another account

• Recognises a person who comes back on a new client account.
• You choose what counts as the same person: the document number, the name + date of birth, or either.
• You choose what to compare with: identities you banned, banned + rejected, or any other account.
• Only a keyed fingerprint is stored, never the number itself.
• On the verification page, click Ban this identity, or tick Ban identity when you reject.

Verified name vs account

• Compares the name on the ID with the client profile, the client's contacts, the billing name of saved payment methods, and the payer name of recent PayPal/Stripe payments. Each source has its own switch.
• You set the similarity needed, and whether one name or all names must match.
• Word order, accents, hyphens and middle names are tolerated.

Company check (KYB)

• For clients with a company name, eKYC Guard looks up the company number (the WHMCS Tax ID, or a client custom field you choose) in a public registry:
  • Norway: Brønnøysund Register (free)
  • EU: VIES (free)
  • UK: Companies House (free API key)
• A company that is not found, closed, or registered under another name triggers your action.
• A missing number or a registry outage is ignored, flagged or sent to review, as you choose. It is never rejected.

Smart triggers (Settings → Enforcement & scope → Smart triggers)

Set When is KYC required to Only when an order meets the conditions, then pick one or more:

• the client's first order
• an order total at or above an amount (other currencies are converted)
• a WHMCS fraud score at or above a value (MaxMind, FraudLabs Pro)
• a client registered within N days

Choose whether any condition or all of them must be met. Once an order triggers, that client needs KYC until verified. Completed orders from before you switched this on never trigger.

Sensitive actions (Settings → Sensitive actions)

Require a verified identity before the customer can:

• get a domain transfer (EPP) code
• remove the registrar lock (locking is always allowed)
• change domain contacts
• change the account email address
• change a service password
• run service buttons such as reboot, rebuild or reinstall (all of them, or only the ones you list)

Apply this to every client, or only to clients in the KYC scope, and write your own message. Actions started by an administrator are never blocked.

9. Daily work: reviewing, alerts & statistics

Reviewing

Addons → eKYC Guard lists every verification, with filters and bulk actions. Open one to see:

• the documents
• the provider result
• the risk panel (IP, network, country)
• the fraud-check findings, with links to matching accounts
• the scope decision
• the full history

You can then:

• Approve
• Reject, choosing from your ready-made reasons or writing your own
• Upload documents on the customer's behalf
• Re-run checks

Every ticket opened from a client account shows the client's verification status to your agents, with a button that fits the status: Send KYC Invite Email, Resend KYC Email or Review Documents.

Alerts (Settings → Alerts)

Turn on any of these channels:

• Telegram: bot token + chat ID
• Slack: incoming webhook
• Discord: webhook
• Your own webhook: JSON, signed with X-Ekyc-Signature when you set a signing secret

Then pick the events: a verification is waiting for review, a fraud-check finding, an order is held, a sensitive action is blocked, rejected, or verified.

Press Send a test alert (saved settings) to check the channels. Alerts include the client number and a link to the verification. The customer's name is included only if you tick Include the customer's name. A failing channel never blocks anything; the failure is written to the activity log.

Continue on your phone (Settings → Client experience)

When this is on, the verification page shows a QR code. The customer scans it and finishes on the phone, without logging in there. They can take document photos and a selfie with the camera, or use a provider that reports back by webhook.

• The link works once, for that customer only, and expires after the minutes you set (default 30).
• The computer page updates by itself when the phone is done.
• DigiLocker is not offered on the phone, because it needs the logged-in client area.

Statistics (Addons → eKYC Guard → Statistics)

For the last 7, 30, 90 or 365 days you can see:

• verifications started, verified and rejected, and the acceptance rate
• the median and average time to a decision
• customers who stopped half-way
• reviews waiting now
• a per-provider table with costs (enter each provider's price under Settings → Advanced)
• orders held and released
• fraud-check, AML, risky-IP and sensitive-action findings

10. Settings reference

Secrets are never shown after saving. Leave the field blank to keep a secret, or tick Clear to remove it. Every change is written to the activity log (setting names only, never values).

11. Upgrading

1. Download the new version from your client area.
2. Upload the modules folder over the existing files (overwrite).
3. Open Addons → eKYC Guard once. WHMCS runs the upgrade automatically.

Your settings, verifications and documents are kept. New features arrive switched off. The changelog is in the zip (CHANGELOG.txt) and on the marketplace page.

12. Troubleshooting

Customers are not being asked to verify. Check these in order:

• Block provisioning until verified is on.
• The licence is valid (Settings → Licence).
• The client, product and TLD are in scope (Settings → Enforcement & scope).
• If country rules or smart triggers are on, the customer meets them. The client's verification page shows that decision.

A provider says "connected" but customers stay "In progress". The webhook is not reaching you. Copy the Webhook URL from the provider panel again into the provider's dashboard. Make sure the site uses HTTPS and that a firewall or Cloudflare rule does not block webhook.php. For Didit, Stripe Identity, Persona and Onfido, the daily run also picks up missed decisions.

DigiLocker returns an error after login. The Redirect URI registered with DigiLocker must exactly match the one shown on the DigiLocker panel.

"Uploads are refused" or an encryption warning. The PHP sodium extension is missing while encryption is on. Enable sodium (cPanel → Select PHP Version → Extensions), then reload the Settings page.

Alerts don't arrive. Press Send a test alert: it shows which channel failed. Failures are also listed in the activity log as alert.failed.

A customer says the QR code "expired". They reload the verification page on the computer to get a new code.

"Cannot declare class Arahoster\Licensing\License". Another Arahoster module uses the same licence client. Update both modules to their latest versions.

Uninstalling

Deactivating the module (Configuration → Addon Modules → Deactivate) keeps your data, so you can reactivate later. To remove everything, deactivate and then drop the mod_ekycguard_* tables and delete the storage folder shown on Settings → Data & privacy.

13. Support

Open a ticket in the client area at https://me.arahoster.com (Support → Submit Ticket). Please include your WHMCS and PHP versions, the eKYC Guard version (Settings → Licence), and what you see on screen.