Install and configure WHMCS to work with the HOSTKEY billing system¶

In this article

• Required Software
• Module installation
• Activate module in WHMCS
• Loading and Deleting Information from HOSTKEY Using Console Commands
• Currency Configuration for Price Exporting
• Customize specific products for resale
• Edit a specific product
• Payment activation for ordered products
• Examples and tips
• Typical errors and solutions

Required Software¶

• reseller module for WHMCS: download;
• WHMCS version 8.8 or higher.

Module installation¶

Extract the contents of the archive to the root of the accounting system.

1. Download and unzip the module archive to the WHMCS root

   Extract the contents of the archive to the root of the accounting system.

   WHMCS root is where the files configuration.php, folders vendor/, modules/, includes/ are located.

   Via SSH:

   cd /path/to/your/whmcs
   

   unzip /path/to/HostkeyResellerMod.zip
   

   Via FTP: Upload the archive contents to the WHMCS root, agreeing to merge the folders.

2. Check the structure after unpacking

   The following should appear:

   • modules/addons/hostkeyresellermod/
   • modules/servers/hostkeyresellermod/
   • modules/gateways/callback/hostkeyresellermod.php
   • includes/hooks/hostkeyresellermod.php

   Key files:

   • modules/addons/hostkeyresellermod/hostkeyresellermod.php
   • modules/addons/hostkeyresellermod/cron.php
   • modules/addons/hostkeyresellermod/clean.php
   • modules/addons/hostkeyresellermod/import.ini (optional)

3. Refresh your admin panel session

   Log out and log back into the WHMCS admin panel. Clear your browser cache if necessary.

Common problems when copying¶

• Files in the wrong folder: The module will not appear in the list if it is in a subfolder rather than the WHMCS root.
• Rights/Owner: Incorrect rights prevent activation/display.
• Browser cache/session: re-login solves the "module is not visible" problem.

Activate module in WHMCS¶

1. Open the list of addon modules

   After copying the module to the WHMCS directory and configuring file system permissions, you need to activate the module. To do this:

   • Path: System Settings → Apps & Integrations → Addon Modules.
   • Find HOSTKEY VPS/Dedicated.

   

2. Activate the module and go to settings

   • Click Activate.
   • Then Configure (or Settings) to open the settings form.

   

3. Fill in the module settings and save

   Fields:

   • API Url — HOSTKEY billing API address:
   • International: https://invapi.hostkey.com/ (default).
   • API key — access key to the HOSTKEY API. Obtain it by following instructions; keep it secret.
   • Preset name prefix — name prefix (default HKP-) to visually distinguish HOSTKEY products in WHMCS listings.
   • Default product group — WHMCS product group for created products (default Hostkey servers).
   • Logging of requests to Hostkey API — enable for debugging if necessary.

   Click Save Changes.

   

4. Set up access (Access Control)

   Check the administrator groups that need access to the module (we recommend enabling "Administrators").

   Attention

   If you do not mark any groups under Access Control, the module will not be available for that group and will not be displayed in the Addons menu, even for the administrator.

   If everything is done correctly (including setting permissions), the HOSTKEY VPS/Dedicated section will appear in the Addons menu.

5. Open the module and configure the import of products

   Go to Addons → HOSTKEY VPS/Dedicated and select the products you wish to resell:

   • Import VPS products — for VPS/VDS;
   • Import Bare metal products — for dedicated servers;
   • Import GPU products — for GPU servers.

   For each marked category, set the markup and format:

   • In percentage: enter the value and leave "%" (example: "10 %").
   • In fixed currency: enter the value and select the WHMCS currency (example: "5 USD").

   Select the rounding mode in Round price to:

   • Not round — without rounding.
   • 0.1, 0.2, etc — up to tenths.
   • 0.25, 0.5, 0.75 — up to quarters.
   • 0.5, 1.0 — up to half.
   • 1.0 — to whole numbers.

   

   Then click the ImportProduct/AdjustPrice button.

   Note

   For the first run, we recommend using another method, as when loading a large amount of information, the page may end with a 504 code. The first time you do a bulk import, there may be a long loading time; if 504, use the console import.

6. Successful download and what to do next

   If the module is correctly connected and activated, a message about successful download of HOSTKEY products will appear and a suggestion to go to the product specific settings in the System Settings → Product/Services menu.

   

   Go to Product/Services:

   • Check the created groups and products.
   • If necessary, open the product, set prices/periods on the Pricing tab; on the Details tab, uncheck Hidden so that the product is displayed on the showcase.

   

   Note

   In case of large amount of information, the page may terminate with code 504 Gateway Timeout. For the first loading of the product list we recommend to execute the command in the billing root.

Loading and Deleting Information from HOSTKEY Using Console Commands¶

cron.php Execution¶

Used to load information from Hostkey. Execute the command from the root of your website:

php modules/addons/hostkeyresellermod/cron.php

clean.php Execution¶

Deletes information previously received from HOSTKEY. Execute the command from the root of your website:

php modules/addons/hostkeyresellermod/clean.php

Important: import.ini takes precedence over admin settings¶

If an import.ini file exists in modules/addons/hostkeyresellermod/, the import will be based on the settings in this file and will overwrite/ignore the settings specified via the admin panel on the Addons → HOSTKEY VPS/Dedicated page.

We recommend using import.ini if import via web interface is unstable (freezing, 504) or when you run import via cron/console.

If you want to configure import via admin panel, delete or rename import.ini:

rm modules/addons/hostkeyresellermod/import.ini

After deleting/renaming the file, the import will again use the values specified in the admin panel.

Parameters in import.ini¶

During operation, the command uses the modules/addons/hostkeyresellermod/import.ini file (if it exists).

Parameters in import.ini:

• template = 5 — replace 5 with the ID of the desired email template from WHMCS (you can see it in the Email Templates section)
• round = 0 — price rounding (0 = do not round, 10 = up to 0.1, 4 = up to 0.25, 2 = up to 0.5, 1 = up to 1.0)
• vps = 10 % — VPS markup
• bm = 50 USD — Bare metal markup
• gpu = 100 RUB — GPU markup

Example import.ini:

[general]
round = 0
template = 5
[markup]
vps = 10 %
bm = 50 USD
gpu = 100 RUB

The file has two sections:

1. The general section contains the round parameter, which controls rounding. Possible values for the parameter:

   • 0 — no rounding;
   • 10 — rounding to the nearest tenth;
   • 4 — rounding to the nearest quarter;
   • 2 — rounding to the nearest half;
   • 1 — rounding to the nearest whole number.

2. The markup section contains the percentage markup for each group.

   If the import.ini file does not exist or the default option is used, no markup or rounding is applied.

Automatic preset update (cron)¶

We recommend setting up a schedule once a day, during off-peak times.

Example crontab (every day at 03:30; replace the paths to whmcs with your own):

30 3 * * * /usr/bin/php /path/to/whmcs/modules/addons/hostkeyresellermod/cron.php >/dev/null 2>&1

Schedule tips: see briefly about cron, assistant — crontab.guru.

Currency Configuration for Price Exporting¶

To accurately export product prices, you need to configure currency rates relative to EUR or USD and between them. This can be done in the Payments >> Currencies section.

Customize specific products for resale¶

By going to System Settings >> Product/Services you will see a table of all the products available to you for resale.

By clicking on the icons in the rightmost columns, you can change the product settings or remove it from the list. Most of the settings are determined by the WHMCS settings and we will only focus on those that are critical for resale.

Edit a specific product¶

Clicking on the Edit icon will take you to the Edit Product parameter modification section.

Detail tab¶

This tab allows you to change the product name that will be displayed on your storefront.

Also, by checking the Hidden to hide the product from the order form without removing it.

Price tab¶

Use this tab to set the price of your product in the currencies available to you.

You can set three types of payment (Payment Type):

• Free - the product is distributed free of charge;
• One Time - one-time payment for one month of use;
• Recurring - recurring payment for a period of time.

You set the price for each period and currency separately, giving you the flexibility to adjust your pricing policy:

• One Time/Monthly - One time payment or recurring monthly payment.
• Quarterly - payment every quarter (3 months)
• Semi-annual - payment every six months (6 months)
• Annual - Payment for one year (12 months)

There are two separate prices available to you:

• Setup Fee - the price for installing the product;
• Price - the selling price of the product.

After changing the parameters and price, click Save Changes and save the settings for this product.

After confirming the successful saving of the settings, click and the button in the upper right corner Back to product list to return to the product table.

Once configured, products appear in the client dashboard.

Payment activation for ordered products¶

To pay for any ordered products, your HOSTKEY account balance will be used. Please ensure that the automatic payment from balance mode is enabled.

Examples and tips¶

• Example of markup and rounding: price 123.56 with markup of 10% and rounding to 0.5 → 136.0.
• Currencies: check Payments → Currencies - the rates to EUR/USD and between the currencies used should be set up.

Typical errors and solutions¶

• Invalid API key / 403: check the validity of the API key, URL (.com), no extra spaces.
• Module is not visible in Addons: check groups in Access Control, refresh session, check file/owner rights.
• 504 Gateway Timeout on import: Use console import, increase max_execution_time.
• Prices seem "at a loss": set your price in Pricing higher than the purchase price; check the markup and rounding.
• Error 503: To find out, try to check the server error log error.log or php_error.log

Some of the content on this page was created or translated using AI.