Developer notes

File map

app/addons/kv_vendor_kyc_verification/
  addon.xml                       settings, 6 tables, 2 privileges, 3 e-mail templates, install/uninstall functions
  init.php / func.php             hooks, settings info handlers, storefront data, licence helpers
  controllers/backend/kv_vendor_kyc_verification.php   admin pages, vendor Verification page, downloads, cron
  controllers/backend/companies.pre.php                 payout hold in core Accounting
  controllers/backend/kv_vendor_payouts.pre.php         payout hold in Vendor Payouts Automation
  controllers/backend/products.pre.php                  "Add product" notice for restricted vendors
  controllers/backend/index.post.php                    vendor dashboard notice
  controllers/frontend/init.post.php                    badge data for the storefront templates
  controllers/backend/kv_vendor_kyc_verification_license.php   "Check now" and licence cron
  schemas/menu/*.post.php            admin menu (Vendors) and vendor panel menu
  schemas/permissions/*.post.php     privileges, vendor modes, cron as trusted controller
  schemas/block_manager/blocks.post.php   block cache: our table + licence/settings key on product and vendor blocks
  Tygh/Addons/KvVendorKycVerification/
    Config.php      settings
    Types.php       document types and their scope (plans, countries, business type), install defaults
    Documents.php   submissions, approve/reject/re-upload, expiry, queue, retention, erasure
    Files.php       secure storage: upload checks, AES-256-GCM, download, deletion
    Vendors.php     requirement states, levels, restrictions, storefront map
    Notifier.php    e-mails
    Cron.php        scheduled task (expiry, levels, reminders, retention)
    Log.php         audit log
    Vrb.php         optional integration with Vendor Onboarding & Registration Builder
    StorageData.php run marks (files instead of storage_data while the full page cache is on)
    License/, Upgrade/   licence client, self-healing upgrades
design/backend/templates/addons/kv_vendor_kyc_verification/   admin + vendor panel views, components, licence UI
var/themes_repository/responsive/templates/addons/kv_vendor_kyc_verification/   badge component + hooks
var/langs/en/addons/kv_vendor_kyc_verification.po

Tables

Table	Purpose
`kv_vkyc_types` + `kv_vkyc_type_descriptions`	Document types: required, expiry mode (`N` none, `D` date from the vendor, `M` months after approval), validity months, scope (`plan_ids`, `countries`, `business_type` `''`/`I`/`C`), allowed extensions, size and file limits, status, position; name and instructions per language
`kv_vkyc_documents`	Submissions: vendor, type, status (`P` pending, `A` approved, `R` rejected or new upload requested, `S` superseded), expiry, vendor note, reason, source (`V` vendor, `A` administrator, `R` vendor application), uploader, reviewer, reminder marks, purge time
`kv_vkyc_files`	Files of a submission: original name, storage path, size, MIME type, SHA-256 of the original, encrypted flag
`kv_vkyc_vendors`	Per vendor: level (`U`, `P`, `V`, `E`, `N`), restricted flag, business type, exempt flag, first time documents were required, verified time, earliest expiry. The only table the storefront reads; rows are written only when a value changes
`kv_vkyc_log`	Audit log

Encryption

Files are encrypted with AES-256-GCM (openssl_encrypt). The key is HMAC-SHA256("kv_vendor_kyc_verification|files|v1", config crypt_key). A stored file is KVK1 + 12-byte IV + 16-byte tag + ciphertext. The SHA-256 of the original is kept for integrity checks. Encryption is used only with the local file storage backend; on other backends files are stored as they are (still only through the storage API and the permission-checked controller).

Full page cache (4.21) and block cache

The badge and the hidden products are the same for every visitor. They come from one indexed query on kv_vkyc_vendors per storefront request, so pages cached by the full page cache carry that table as a cache tag and are purged when a level or restriction changes. Product and vendor blocks get kv_vkyc_vendors in their update_handlers and a callable cache key with the licence and settings state. The add-on writes nothing during storefront requests.

Hooks

Core hooks used (identical signatures in 4.17.2 and 4.21.2): get_products and get_product_data (hide products of restricted vendors on the storefront), update_product_pre (no new products from restricted vendors in the vendor panel), delete_company (remove documents, files, log, level), before_dispatch (hourly pseudo-cron from panel page views).

Template hooks: companies:vendor_rating, companies:featured_vendors, companies:product_company_data, companies:products (pre), companies:view (pre).

Hooks of the add-on (fn_set_hook):

Hook	Arguments	Use
`kv_vendor_kyc_verification_document_submitted`	`$doc, $type, &$decision`	Runs after every upload. Integration point for identity verification services: send the files to a provider and set `$decision = ['action' => 'approve', 'expires_at' => <timestamp>]` or `['action' => 'reject', 'reason' => '...']` to review the upload automatically; leave it empty for manual review.
`kv_vendor_kyc_verification_document_reviewed`	`$doc, $action`	After approve, reject or re-upload request.
`kv_vendor_kyc_verification_level_changed`	`$company_id, $old_level, $new_level`	After a vendor’s level changed (`''` as old level for a new vendor row).
`kv_vendor_kyc_verification_is_restricted`	`$company_id, $restriction, &$result`	Change whether a restriction (`payouts`, `hide_products`, `new_products`) applies to a vendor.

File contents of a submission: \Tygh\Addons\KvVendorKycVerification\Files::contents($file_row) returns the decrypted bytes.

Endpoints

Dispatch	Who	Method
`kv_vendor_kyc_verification.manage` (`&tab=vendors`), `.vendor`, `.types`, `.type`, `.log`	Administrators (`view_kv_vkyc`)	GET
`.approve`, `.reject`, `.reupload`, `.set_expiry`, `.admin_upload`, `.import_vrb`, `.update_vendor`, `.erase`, `.update_type`, `.delete_type`, `.run_cron`	Administrators (`manage_kv_vkyc`)	POST
`.verification`, `.upload`, `.update_business`	Vendors (own company only)	GET / POST
`.download&file_id=`	Administrators; vendors for their own files	GET
`.cron`	Console, or HTTP with the core cron password	GET

All POST requests are protected by the core form token.

License check

fn_kv_vendor_kyc_verification_is_licensed() (License\Client::isActive()) together with the Enable setting gates vendor uploads, the restrictions, the storefront badge and the reminder e-mails. Reviews, downloads, the audit log, retention and erasure always work, so documents never become inaccessible. The licence check itself runs only in the admin panel or from cron (php admin.php --dispatch=kv_vendor_kyc_verification_license.check).