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.

• Product groups — tick any WHMCS product groups. Orders containing a product from a ticked group are held.
• Domains — turn on Require KYC for ALL domain orders to hold every domain order, or leave it off and tick individual TLDs, e.g. .cn, .ru. Your per-TLD picks are kept even while the master toggle is on.
• No selection at all means KYC is required for every order.

The triggers are OR-combined: an order is held if it matches any configured rule. This is what lets you keep shared hosting activating in seconds while holding the risky categories.

7. 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 product and domain rules.
• Their existing active services are not touched. Held orders activate automatically once the client verifies.
• A flagged-but-unverified client also sees the client-area verification banner, so they can complete KYC proactively before ordering.

8. Admin dashboard

Open Addons → TPC KYC - Sumsub. The table shows every client with a KYC record.

Status colours

The table is enhanced client-side — search across all columns and sort by any header. Sort defaults to newest review first.

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}

It calls Sumsub's /status endpoint directly, updates the stored status, and prints the result as a small table. Useful when troubleshooting a stuck order.

Manual approval

Occasionally KYC is completed out of band — documents sent by email, a Sumsub review is stuck, an urgent activation is needed.

1. Find the client's row. The green check-mark button appears on any row whose status is not completed.
2. Click it and confirm the browser prompt.

What happens: a CSRF token is validated, the status flips to completed, every pending order for that client is activated via AcceptOrder, and the client receives the user-verification-success email.

9. Handling a rejected client

Rejections are automatic. The status-sync cron marks the record failed with a specific fail reason.

Re-verification flow

The client can retry from the client area:

1. They open Client Area → Verify KYC.
2. The page shows Re-Submit KYC, or Continue Verification if the existing session is resumable.
3. Clicking it fetches a fresh WebSDK link bound to the client's existing externalUserId and redirects them back into the Sumsub flow.

If the Sumsub applicant is locked — common after a hard RED result — the next cron run's name-match pass calls the applicant reset endpoint automatically when a mismatch is detected. For other RED cases you may need to reset the applicant manually from the Sumsub dashboard (Applicant → Reset applicant) before the client can re-submit successfully.

10. 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 Sumsub cron entry in the WHMCS Activity Log. If nothing appears for hours, the cron is not executing — check your server cron, the URL and path, and the CronSecret value.
2. Check the KYC row status. Run Check Status for that client. Whatever Sumsub returns is the source of truth.
3. Sumsub says completed but the order is still held? The cron fired but AcceptOrder failed — look for Sumsub cron: failed to activate order {id} in the activity log. Usually the order status or its items changed in WHMCS.
4. Sumsub says pending or onHold? The client has not finished. Send them the direct link — Verify KYC in their client area — and keep monitoring.
5. Row is failed? Check the fail reason and follow the re-verification flow above.

11. 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.
5. They upload their ID, complete the liveness selfie, and submit.
6. Sumsub reviews. The webhook updates the stored status as the review progresses.
7. On the next cron run, if the review is approved and the age and name checks pass, their orders are activated automatically and they receive Identity Verification Approved (user-verification-success).

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.

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. Dismissing it hides it for the current browser session only — it returns on a new session. It is suppressed on the KYC page itself and on the checkout cart, to avoid stacking warnings during active flows.

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

12. Email templates

Customisation tips

• Match the brand voice of your other WHMCS emails — first-person plural, direct, short.
• In user-verification, always include {$verification_url} on its own line as a clickable link. If omitted, the email falls back to a generic link to the KYC page.
• In user-verification-failed, direct the client to open a support ticket rather than replying to the email. Failure reasons need different handling and admin eyes.
• Consider adding an explicit "why we need this" paragraph in user-verification, linking to a public KYC policy page.

13. Production checklist

A healthy production setup has all of the following.

• Cron running every 15–30 minutes with the correct CronSecret.
• 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.
• All three email templates created and active.
• 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.
• Mandatory KYC rules reviewed, so low-risk products still activate instantly.

Monitoring: review the Activity Log (filtered by Sumsub) weekly during rollout, monthly once stable.

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