KYC Identity Verification for WHMCS

1. Requirements

What your WHMCS install needs before you start.

2. Install the addon

1. Unzip the download and upload the tpckycsumsub/ folder into /modules/addons/ on your WHMCS install.
2. Go to WHMCS Admin → System Settings → Addon Modules, find TPC KYC - Sumsub, and click Activate.
3. Set Access Control to the admin roles that should be able to see KYC data, then save.
4. Open Addons → TPC KYC - Sumsub. The addon provisions its own mod_sumsub_settings table on first load.
5. Go to the Settings tab and paste your License Key. The addon validates it against the TPC license server and caches a local key, so short network outages will not lock you out.
6. Work through the Setup Guide tab — it shows a live readiness checklist of which settings are still missing, plus your install's copy-ready webhook and cron URLs.

3. Sumsub-side setup

Get your credentials and verification level in order before configuring the WHMCS side.

3.1 Create a verification level

1. Log in to the Sumsub dashboard.
2. Go to Applicants → Levels and click Create level, or reuse the default basic-kyc-level.
3. Configure the document types, liveness check, and review policy to match your compliance requirements.
4. Copy the level name exactly — this is what goes into the addon's LEVELS setting.

3.2 Generate API credentials

1. In the Sumsub dashboard, go to Dev Space → App tokens.
2. Click Create new token and give it a descriptive name, e.g. whmcs-production.
3. Copy the App Token — it starts with sbx: for sandbox or prd: for production. This is the APIKEY setting.
4. Copy the Secret Key — this is SECRETKEY. Sumsub will not show it again, so store it somewhere safe.

3.3 The API URL

Sandbox and production both use:

https://api.sumsub.com/

Sumsub uses the same base URL for both environments — there is no separate sandbox hostname. Which environment you reach is decided entirely by the App Token: a token created in Sandbox mode (sbx:) hits the sandbox tenant, a Production token (prd:) hits production. A token created in one mode cannot be used against the other.

4. Cron and webhook

The webhook gives you real-time updates; the cron is the safety net that actually activates orders. Set up both.

4.1 Register the webhook in Sumsub

1. Go to Dev Space → Webhooks → Webhook manager and click Create webhook. Make sure the Sandbox / Production toggle (top-right) matches the environment of your App Token.
2. Name the webhook, e.g. TPC KYC, and set Webhook receiver to HTTP address.
3. In Target, enter your webhook URL:

   https://yourdomain.com/modules/addons/tpckycsumsub/webhook.php

4. Under Webhook types, select applicantReviewed. You may also add applicantWorkflowCompleted. Set Applicant types to All types or Individual.
5. Leave Signature algorithm on SHA256 — the default. The handler also accepts SHA512 and the deprecated SHA1.
6. Sumsub auto-generates a Secret key for this webhook. Copy it.
7. In Addons → TPC KYC - Sumsub → Settings, paste that value into the Webhook Secret field and save.
8. Save the webhook in Sumsub, then click Test webhook and watch the WHMCS Activity Log for a Sumsub webhook entry to confirm delivery.

4.2 Add the cron entry

The cron polls Sumsub for results, runs the age and name checks, activates approved orders via the native WHMCS AcceptOrder API, and sends your email templates. Run it every 15–30 minutes:

*/15 * * * * php -q /path/to/whmcs/modules/addons/tpckycsumsub/tpckycsumsubCron.php

The cron is protected by the CronSecret value on the Settings tab. The Setup Guide tab prints the exact command and URL for your install, with the secret already filled in.

5. The addon tabs

All configuration lives inside the addon, not on the WHMCS module-config screen. Open Addons → TPC KYC - Sumsub and use the tab bar at the top.

6. Choosing which orders require KYC

On Addons → TPC KYC - Sumsub → Mandatory KYC. Five rule types, each with a role: trigger or condition.

How roles combine. An order is held when at least one trigger matches (or no trigger is configured) and every configured condition matches. Rule types you have not filled in are ignored whatever their role.

• Product groups = trigger alone: VPS orders are held, everything else goes through.
• Product groups = trigger, Payment methods = condition: VPS orders paid by card are held; VPS orders paid by bank transfer go through.
• Countries (exclude EU) = condition alone: every order from outside the EU is held.
• No rule configured at all → every new order is held. Configure at least one rule before go-live.

Always true, whatever the rules:

• Renewal-only orders are never held (renewals with no new service, add-on or domain), not even for flagged clients.
• Verified clients are not held again — unless the order contains an in-scope domain with a third-party registrant.
• Switching an unpaid order's invoice to a ticked payment method re-runs the rules and can hold the order; switching away never releases one.
• Every hold records why: the dashboard shows it under the client's status (Held: #1234 · trigger groups (gid 3) + condition gateways (paypal)) and the Activity Log repeats it.

7. Domain registrant verification

From 1.9 the addon verifies the registrant named on a domain, not only the WHMCS account holder — what EU registries and NIS2 Article 28 ask of registrars and resellers: accurate, verified registration data for the person or company that actually holds the domain.

Turning it on

Registrant verification uses the Domains rule of the Mandatory KYC tab and nothing else: a domain is in scope when Require KYC for ALL domain orders is on or its TLD is ticked. If the Domains rule is not configured, no registrant is ever asked — even when the addon holds every order because no rules are set.

Registrants are verified against Settings → Registrant level (REGISTRANT_LEVELS; empty = same as LEVELS). That Sumsub level must include the Applicant data step.

What happens on a domain order

1. The client places an order with an in-scope domain. The addon looks at the registrant: the account holder's own details, or a third party (a saved Contact, or details typed at checkout).
2. Own details: nothing extra. The client's own verification covers the domain. If the client is unverified, the order is held for the client as usual.
3. Third party: the order is held at Pending KYC for the registrant. The registrant receives registrant-verification with their own Sumsub link at the contact's email address; the account holder receives registrant-pending-owner. If the account holder is unverified too, the order waits for both.
4. The registrant verifies in Sumsub like a client would. The same checks apply: age, Sumsub answer, name match against the registrant data, document country, duplicate document.
5. When every subject the order waits for is verified, the cron activates the order and the domain is sent to the registrar. The registrant gets registrant-verification-success, the account holder registrant-verified-owner.

A verified registrant is remembered for that client's later orders. They verify again only when their phone or country changes or the verification has expired; address and company changes are just stored. An edited saved Contact is re-checked at the next domain order.

The guard in front of the registrar

Even if an order is accepted by hand (Accept Order, Register in the admin area) or placed through the API, the addon checks the registrant just before the registrar module is called. If the registrant is not verified, or the contact data about to be sent differs from what was verified, the registrar call is stopped with a message, the action is parked, and the registrant gets a fresh link (at most every Registrant link resend interval hours). The cron sends the registration or transfer automatically once the registrant has verified — nothing to redo by hand. Domains of orders placed before the 1.9 upgrade are let through (audited as pre_feature_order).

On the dashboard

Registrants appear as their own rows with Subject = Registrant, the same status pills and reasons as clients, and the held orders they block. Approve Manually works on a registrant row too and activates the orders that no longer wait for anyone else. KYC history lists every registrant action: links sent, corrections, switches, guard blocks.

When the name on the document does not match

If Sumsub approves the registrant but the document name does not match the registrant data, the order stays held and you are alerted. You do not have to act: the account holder sees the mismatch in their client area and can fix it themselves — correct the details, adopt the name from the ID document, or switch the order to a different registrant (see What clients see). Or you approve manually after checking.

8. Requiring KYC for a specific customer

Sometimes you need to require KYC for one client regardless of what they order — a flagged or high-risk account, for example.

Two ways to flag a customer

• From their profile — open the client in WHMCS admin and click the Require KYC action button. It becomes Remove KYC requirement once set.
• From the Customers tab — type a client ID or email and click add. The table lists every flagged client with their current KYC status and a Remove button.

What flagging does

• The client's new orders are held at Pending KYC until they complete verification — regardless of the Mandatory KYC rules (renewal-only orders excepted).
• Their existing active services are not touched. Held orders activate automatically once the client verifies. Removing the flag does not release orders that are already held.
• A flagged-but-unverified client also sees the client-area verification banner, so they can complete KYC proactively before ordering.
• Flagging and un-flagging are written to the audit log.

9. Admin dashboard

Open Addons → TPC KYC - Sumsub. The table shows every client and registrant with a KYC record, newest review first.

Status pills

Search across name, country and status; page size 10 / 25 / 50 / 100 / All.

Checking one applicant's status live

To force a fresh status pull without waiting for the cron, open this URL, replacing {userid}:

addonmodules.php?module=tpckycsumsub&checkstatus={userid}

Manual approval

Use Approve Manually when a row waits for your decision (Review Complete (Pending Approval)) and you have satisfied yourself about the identity, or when KYC was completed out of band.

1. Find the row. The green check-mark button appears on any row whose status is not Approved.
2. Click it, confirm the browser prompt, then type an optional note (why you approved). Cancelling either prompt aborts.

What happens: a CSRF token is validated, the approval and your note are written to the audit log, every held order that no longer waits for another subject is activated via AcceptOrder, and the subject receives the success email. If an order fails to activate the row becomes Activation Failed and a warning tells you which order.

10. Holds that need your decision

These never fail the client and never email them. They show as Review Complete (Pending Approval), write review_hold to the audit log and send you the alert client #N needs a manual KYC review.

11. Handling a rejected client

Rejections are automatic and come from Sumsub's review or the age gate. Each outcome is applied once per Sumsub attempt, so a rejection does not re-send the failure email every cron run.

Re-verification flow

1. The client opens Client Area → Verify KYC.
2. The page shows Try again (retry) or Re-Submit KYC / Continue Verification.
3. Clicking it fetches a fresh WebSDK link bound to the client's existing applicant and redirects them back into the Sumsub flow. A new submission is a new attempt and is evaluated afresh.

If the Sumsub applicant is locked — common after a final RED result — reset it from the Sumsub dashboard (Applicant → Reset applicant) before the client re-submits.

12. Reminders, automatic cancellation and alerts

All of this runs inside the status-sync cron. Configure it under Settings → Held orders, alerts and retention.

• Reminders (Reminder emails after (hours), default 24,72): at each age a held order reaches, the subject it waits for — client or registrant — gets one reminder with a fresh 7-day link. One reminder per client per run, none while their documents are under review, none to rejected registrants. Empty = no reminders.
• Automatic cancellation (Cancel held orders after (days), off by default): unpaid orders whose subject never started a review are cancelled after N days and the client gets user-verification-cancelled listing the orders. Paid orders are never cancelled — you get an alert instead. Orders you accept or cancel yourself in WHMCS stop being tracked on the next run.
• Alerts go to every admin who receives WHMCS system emails (subject TPC KYC: ...) and, if set, to a Slack / Teams alert webhook URL. The same alert is repeated at most every Repeat the same alert at most every (hours) (default 24). Alerts carry ids only, no personal data.

13. Audit log and retention

Addons → TPC KYC - Sumsub → Audit log shows the newest 500 entries with when / client / by (admin or system) / action / detail. Filter by client ID or action; from the dashboard, KYC history opens it for one client.

You will see manual_approve (with your note), flag_on / flag_off, settings_change (which keys changed; secrets only as changed), review_hold, account_change, auto_cancel, relationship_ended / relationship_resumed, retention_purge, and the registrant entries (registrant_*, registrar_action_blocked, pre_feature_order, test_mail_sent).

Retention

When a client account is closed or deleted, the retention clock starts on their KYC row. After Keep KYC records after the account ends (years) (default 5 — the Romanian Law 129/2019 term) the cron deletes the local KYC record and its held-order rows, once a day, and writes retention_purge.

14. Diagnosing a stuck order

A client says they finished KYC but their order is still Pending KYC. Work through this in order.

1. Confirm the cron ran. Look for a recent cron entry from the addon in the WHMCS Activity Log (it ends with a done (...) summary). If nothing appears for hours, the cron is not executing — check your server cron, the URL and path, and the CronSecret value. previous run still active — skipping. means a run is stuck or still going.
2. Look at the dashboard row. Review Complete (Pending Approval) with a reason underneath means the order waits for you (section 10). Action needed or Failed means it waits for the client.
3. Is it a domain order with a registrant? Look for a row with Subject = Registrant for that client. The order waits for the registrant, not the client. The client can resend the link or change registrant from their client area.
4. Check the KYC row status live. Run Check Status. Whatever Sumsub returns is the source of truth. pending / onHold → the client has not finished; send them to Verify KYC.
5. Row is Approved but the order is still held? AcceptOrder failed — look for failed to activate order {id} in the Activity Log (usually the order or its items changed in WHMCS). Fix the order and let the cron retry, or accept it by hand.
6. Order accepted but a domain was not registered? The registrar guard stopped it (registrar action blocked in the Activity Log). It is sent automatically once the registrant verifies, or approve the registrant manually.

15. What clients see

First-time verification from checkout

1. The client completes checkout and receives the standard WHMCS order confirmation.
2. Seconds later they receive a second email — Identity Verification Required (user-verification). It contains the direct verification link, valid for 7 days.
3. In the client area, a yellow banner appears at the top of every page: "Identity verification required. Complete KYC verification to activate your orders." The close button dismisses it for the current browser session.
4. Clicking the verification link takes them into Sumsub's hosted WebSDK flow: ID upload, liveness selfie, submit.
5. Sumsub reviews. The webhook updates the stored status as the review progresses.
6. On the next cron run, if the review is approved and the checks pass, their orders are activated and they receive Identity Verification Approved (user-verification-success). If a check holds them for admin review, the KYC page says their documents were received and are being reviewed; nothing is emailed until an admin decides.
7. If they do not finish, they receive a reminder with a fresh link at the configured ages (default after 1 and 3 days) and — if enabled — a cancellation notice when an unpaid order is cancelled.

Verifying from the client area

Clients can also start or resume KYC without an email. They log in, click Verify KYC in the top navigation, and:

• No record yet — the page shows a form with a Submit KYC button, plus a Personal / Company toggle if applicable. Clicking it creates the Sumsub applicant and redirects to the WebSDK.
• Incomplete record — the page shows Continue Verification or Re-Submit KYC, opening a fresh WebSDK session bound to their existing applicant.
• Retry requested — the page shows Sumsub's What to fix text and a Try again button; the email user-verification-retry carries the same text.

The page also displays the current status and, once completed, the Sumsub and WHMCS names side by side for transparency.

The persistent banner

The yellow banner is the addon's nudge. As long as the client has an unactivated order, an incomplete KYC record, or is flagged on the Customers tab, it appears on every page (and again on the invoice page of a held order). Its wording follows the situation: verification required, your identity verification needs another attempt, or an order is waiting for a domain registrant. Dismissing it hides it for the current browser session only. It is suppressed on the KYC page itself and on the checkout cart.

Domain registrants

When an account holder orders an in-scope domain for someone else, that person has to verify, not the account holder.

The account holder receives registrant-pending-owner, sees a banner saying an order is waiting for a domain registrant, and finds a Domain registrants card on Verify KYC listing each registrant of a held order with their status and these actions:

• Resend verification link — a fresh link to the registrant's email (at most once every Registrant link resend interval hours, default 6).
• Correct details — fix a typo in the registrant's name, email, phone, address or company; the saved Contact is updated too. A changed email or phone always starts a new verification.
• Use the name from the ID document — shown after a name mismatch: adopts the verified name onto the registrant and the Contact, and releases the order.
• Change registrant — move the held order to another Contact or to the account holder's own details. The WHMCS order contact changes too, so the registrar receives the new registrant's data.

When the registrant has verified, the account holder receives registrant-verified-owner and the order activates; on a rejection, registrant-failed-owner. Verified registrants are shown but can no longer be corrected or switched.

The registrant receives registrant-verification at the contact email address, sent from your WHMCS system address: a domain is being registered in their name on behalf of the account holder, please verify your identity. It contains their own Sumsub link (7 days). Then the Sumsub flow, and registrant-verification-success, -retry or -failed depending on the outcome, with reminders at the same ages as client reminders. The registrant never needs a WHMCS login and never sees the account holder's data.

Client-facing pages inherit your theme (Lagom2 and Twenty-One are both supported).

16. Email templates

All templates are created automatically with a default text the first time any addon page or the cron runs; existing templates are never overwritten. Edit them under Setup → Email Templates (type General).

Customisation tips

• Match the brand voice of your other WHMCS emails — first-person plural, direct, short.
• Always keep {$verification_url} on its own line as a clickable link in the verification, reminder, retry and registrant templates. If omitted, the email falls back to a generic link to the KYC page.
• Keep {$kyc_message} in the retry templates — it is Sumsub's own explanation of what went wrong, which is what gets the client through on the second attempt.
• In user-verification-failed, direct the client to open a support ticket rather than replying to the email.
• In registrant-verification, explain in one sentence who is registering the domain and why the registrant is asked (registry rules / NIS2). The registrant may have never heard of you.
• Test registrant delivery with Settings → Send test registrant email before go-live (mail path, From address, SPF).

17. Production checklist

A healthy production setup has all of the following.

• Cron running every 15–30 minutes with the correct CronSecret (it is incremental, so frequent runs are cheap).
• Webhook registered in Sumsub, pointing at https://yourdomain.com/modules/addons/tpckycsumsub/webhook.php.
• WEBHOOK_SECRET identical to the Secret key shown for that webhook in Sumsub's Webhook manager.
• A production App Token (prd:) in Settings, not a sandbox one.
• At least one rule configured on the Mandatory KYC tab (otherwise every order is held), roles reviewed so low-risk products still activate instantly.
• If you sell domains: the Domains rule set to the TLDs that need registrant verification, the registrant level including the Applicant data step, and one test registrant email sent and received.
• Reminder ages, automatic cancellation and the alert webhook set the way you want them; at least one admin receiving WHMCS system emails.
• All email templates present (they are created automatically) and their copy reviewed.
• Access control on the addon restricted to the admin roles that should see KYC data.
• A public KYC policy or FAQ page for the user-verification email to link to.

Monitoring: the admin alerts tell you when something needs you. Review the Activity Log weekly during rollout, monthly once stable; review retention_purge entries monthly and delete the named applicants in Sumsub.

18. Support

Email support is included for the whole license year, direct from the engineers who wrote the addon. Send us your WHMCS version, PHP version, addon version, and the relevant Activity Log lines (filtered by Sumsub) and we can usually pinpoint the issue on the first reply.

19. Changelog

Every release, newest first. Version numbers follow the value reported on the addon's own module config.