Addons for WHMCS

    Addon para funciones avanzadas

    User manual for the WHMCS Domain Management Tool
    MrDomain

    Download from Github

    1 Introduction

    This is the user manual for the MrDomain's Advanced features Addon for WHMCS.

    This software adds new capabilities to the WHMCS administration panel using the MrDomain's API, including:

    • Automatic domain syncing
    • Adding new TLDs to WHMCS
    • Managing existing domains and TLDs
    • Personalized email alerts for new TLDs and price changes
    • Whois proxy for checking domain availability

    1.1  Getting started

    The MrDomain's Domain Management Addon for WHMCS uses the MrDomain's API. You need to have a working API account.

    To activate the module you will need an API USername and API Password that you should have obtained from MrDomain's support team. For more information about the MrDomain's API, visit the online documentation.

    1.2 Available characteristics

    This addon allows to perform the following actions:

    • Update prices and configure existing TLDs in WHMCS
    • Add new TLDs supported by MrDomain but not yet configured in WHMCS
    • Update information and configuration of existing domains in WHMCS
    • Importing existing domains in the MrDomain account that are not yet created in WHMCS
    • Notify via email when new TLDs are added to MrDomain or there's a price change

    The addon will also add a hook to WHMCS to update regularly prices and send notifications. You can learn more about WHMCS hooks on their documentation section.

    1.3 Disclaimer

    WHMCS is a registered trademark of WHMCS Ltd.. MrDomain isn't part or is otherwise affialiated to WHMCS Ltd.. You can get more information on WHMCS Software on its official website.

    2  Installation

    To install the Addon, download the ZIP from our Github repository. Once downloaded, unzip it and you will end up with a folder named src. Upload the contents of the folder inside your WHMCS root directory, usually /path/to/whmcs/ and accept and merge all the changes.

    Once the folder contents are uploaded, access the WHMCS administration panel and go to the addon configuration screen, on Settings > Addon modules. Locate an addon named DonDominio Manager Addon and click on the Enable button. Once activated, click on Configure and adjust the roles that will be able to use the Addon (usually, Full Administrator).

    Addons

    If the module was enabled correctly, now you should be able to configure and use it.

    2.1 Minimum configuration

    To start using the module, first it needs to be configured. The minimum required configuration is your MrDomain API details (username and password). To enter your API credentials, access Addons > DonDominio Manager Addon.

    Menu

    Since you have not yet configured the addon, the only screen you'll be able to access is the settings screen. In this screen, fill the following fields:

    API Username: Write in your API username
    API Password: Write in your API password

    Then, click Save changes and the addon will be activated. It may take a few seconds to activate it while the addon builds the internal TLD cache. Once finished, you will be able to access all other options.

    API Settings

    2.2 Uninstallation

    To remove the addon, first go to Settings > Addon modules and locate DonDominio in the list. Click on the Disable button. All information stored in the database will be lost, except for the created TLDs and domains (and all associated settings).

    To completely delete the addon from your WHMCS installation, go to /path/to/whmcs/modules/addons, locate a dondominio folder and delete it.

    2.3 Multi-language support

    The addon is available both in English and Spanish. It will automatically change depending on the language selected on your WHMCS administration panel. If you choose a different language from those two, the addon will default to English. For more information on language settings for WHMCS, check the documentation.

    3 Home

    This is the home page that we access when entering the MrDomain Module.

    The purpose of this section is to report if there have been problems related to the Module and to provide the links to consult the documentation of the Module and its repository on GitHub.

    Home

    4 Modules Status

    The Status module can be found in the Admin section Admin > Status and is intended to report on the status and information of the various components relevant to the operation of the Registrar and Addon of MrDomain.

    The information provided is: the WHMCS version, the version and status of the Modules, the status of the SDK, the status of the connection with the API and the status of the Premium Domains.

    The following actions can also be performed: Check API status, configure Premium Domains, activate and configure Registrar.

    The More Info and PHP Info buttons show more information about the system configuration.

    Status

    5 Settings

    The Settings module is located within the Admin section Admin > Settings and allows you to configure behaviours and functionalities from the addon.

    The settings are divided under tabs for easier use.

    5.1 DonDominio's API

    API

    Field Values Description
    API Username Text Your API Username
    API Password Text Your API Password

    5.2 Price adjustment

    Price

    Field Values Description
    Update prices in WHMCS when they change Yes/No When there's a price change in MrDomain, also update TLD prices in WHMCS.
    Registration increase Number Quantity (fixed or %) to add to TLD prices when changing registration prices in WHMCS.
    Transfer increase Number Quantity (fixed or %) to add to TLD prices when changing transfer prices in WHMCS.
    Renewal increase Number Quantity (fixed or %) to add to TLD prices when changing renewal prices in WHMCS.

    5.3 Automatic notifications

    Notifications

    Field Values Description
    Enable notifications Yes/No Enable or disable notfications on the module globally
    Email for notifications Email The Email address that will receive the notifications. If left blank, no notifications will be sent.
    Enabled notifications N/A The multiple kinds of notifications available. Enable the ones you want to receive notifications for.
    Watch/Ignorelist N/A Watch/Ignorelist feature.

    To use the Watch/Ignorelist feature, first select one of the available modes:

    • Do not use Watch/Ignorelist: The feature will be disabled.
    • Watch only these TLDs: Receive notifications only for selected TLDs.
    • Ignore these TLDs: Do not receive notifications for selected TLDs.

    Then, select one or more TLDs from the left list (Available TLDs) and click >> to move them to the right list (Selected TLDs). To remove a TLD from the selected list, select it and click <<.

    5.4 Cache status

    Cache

    This addon stores some information on the local database (also known as cache). This screen displays information from the cache currently stored in the database.

    • Last update: Last time prices were downloaded from the MrDomain's API.
    • TLDs in cache: Number of TLDs stored on the cache and supported by the MrDomain's API.
    • Rebuild cache: Check this checkbox and click on Save changes to empty the current cache and redownload all the prices from the MrDomain's API again.

    5.5 Whois Proxy

    Whois

    • WHMCS Domain: The URL that leads to your WHMCS frontend
    • Allowed IP Address: One or more IP addresses, separated by semi colons, that are allowed to use the Whois Proxy

    6 Balance

    The Balance module is found in the administration section Admin > Balance and has the purpose of informing about the remaining balance in the configured API user and the warning threshold.

    Balance

    7 Price update

    The Price update module is located within the TLDs and Price section TLDs and Price > Import and allows you to update the prices for your TLDs using the information available on MrDomain's API.

    TLDs Princing

    7.1 Price update

    Heads up In order to update prices, the TLDs must be configured to use MrDomain as registrar. See the Change registrar function in this same module for more information, and the WHMCS Registrar Module documentation for more information.

    To use the Price update function, first select all the TLDs you want to update and then click on Update prices. The addon will apply to all selected TLDs the latest prices downloaded from the MrDomain's API, taking into account price increases defined in the Settings.

    7.2  Change registrar

    In order to manage a TLD using this addon, it must be configured to work with the WHMCS Registrar Module from MrDomain. Select all the TLDs you want to use with this module and click Change registrar to DonDominio. They will be automatically configured to use the module from that moment.

    Heads up Any other registrar module you were using with those TLDs (if applicable) will be disabled for all those TLDs.

    7.3 Manual price adjustment

    You can manually adjust prices for TLDs instead of using the API prices in conjunction with the price modifications defined on the Settings screen. Click on the Editar icon to access the manual prices screen.

    On this new screen, you'll find the following options:

    Do not update prices automatically for this TLD Enable this option to make the automatic price adjustment tool ignore this TLD.

    *Enable individual settings Enable this option to manually adjust prices for this TLD instead of using the regular system.

    Register increase A registration price increase to be applied to the regular registration price for this TLD. The registration price is obtained via the MrDomain's API, and you can choose to apply it as a Fixed increase (adding this quantity to the price on MrDomain), as a % (adding a percent to the price on MrDomain), or rather Disable it and set the price directly as you entered it in this field (ignoring all other prices, increases, and so on).

    Transfer increase and Renewal increase Both work like Register increase explained above, but for transfers and renewals, respectively.

    To save the settings, click on Save changes.

    When prices are updated for this TLD (automatically or manually) the settings entered in this screen will take effect.

    Manual TLD Pricing

    8 Available TLDs

    The Available TLDs module can be found in the TLDs and Price section TLDs and Price > Available TLDs and allows you to create new TLDs supported by the MrDomain's API but not yet created in WHMCS.

    When creating a new TLD, the most recent prices obtained from MrDomain's API will be used, and the WHMCS Registrar Module from MrDomain will be automatically enabled for it.

    Available TLDs

    8.1 Filters (TLDs)

    This module has filters to search for TLDs in the list, you can filter by all or part of a TLD to filter the list by it.

    8.2 Adding TLDs

    Select one or more TLDs you want to add to your WHMCS installation and click on Add to WHMCS to create them automatically. The new TLDs will have the latest prices obtained from the MrDomain's API and will be configured to use the WHMCS Registrar Module from MrDomain.

    Once added, the TLDs will be available to your customers to select them and register and transfer domains.

    Alternatively, you can click on the Añadir icon to add that specific TLD.

    9 Domain Management

    The Management module is located within the Manage domains section Manage domains > Manage and allows us to check and update the information of the existing domains in your WHMCS installation. It will also allow you to configure those domains to use the WHMCS Registrar Module from MrDomain.

    Domains

    9.1 Filters (Domains)

    This module has filters to search for domains in the list, it allows us to filter by the following fields: Domain name, TLD, Registrar and State.

    9.2 Registrar change

    Select one or more domains from the list and click on Switch registrar to DonDominio to configure those domains to use the WHMCS Registrar Module from MrDomain.

    9.3 Update information

    Heads up
    In order for the addon to be able to update the information of a domain it must be first configured to use the WHMCS Registrar Module fromMrDomain.

    Select one or more domains from the list and click on Update information from DonDominio to update the domain information according to the information available through the MrDomain's API. The information updated will be the domain status and its expiration date.

    Alternatively, you can click on the Sincronizar icon to update that domain's information.

    9.4 Contacts

    You can perform contacts mass changes from this screen using a MrDomain Contact ID.

    MrDomain Contact IDs The MrDomain Contact IDs are special codes that identify domain contacts inside MrDomain accounts. They are something similar to AAA-00000 and you can find them on the MrDomain administration panel.

    To see your Contact IDs, go to your MrDomain administration panel on https://www.mrdomain.com and then click on Admin at the top left, then on Tools and finally on Contacts. On the list that will appear, you will find each Contact ID under the column Contact ID. This is the code that you need to write on the corresponding field.

    Select one or more domains that you want to modify, write the Contact ID in the DonDominio Contact ID field and then click on one of the following buttons:

    • Update owner contact: This will update the owner contact for the domains using the Contact ID you provided.
    • Update admin contact: This will update the admin contact for the domains using the Contact ID you provided.
    • Update tech contact: This will update the tech contact for the domains using the Contact ID you provided.
    • Update billing contact: This will update the billing contact for the domains using the Contact ID you provided.

    Heads up This change may take several minutes when applied to a large amount of domains at once.

    9.5 Transferir a DonDominio

    Through the Transfer button found in the domains that do not have MrDomain as a registrar, the domain can be transferred to MrDomain indicating the Authcode/EPP

    9.6 Dominio

    From the list of Domain Management you can access a specific domain, this view offers the possibility of synchronizing the status of the domain and consulting its information and history to the MrDomain API.

    Domain

    10 Transferir dominios

    The Transfer module can be found in the Domain Management section Manage domain > Transfer and allows us to massively transfer domains to MrDomain.

    Transfer

    11 Import domains

    The Import domains module is located within the Manage domains section Manage domains > Import and allows you to import existing domains on your MrDomain account to your WHMCS installation. The imported domains will be created using all the information available about them on the MrDomain's API and will be assigned to the customer of your choice.

    Alert In order to import domains, a new order will be created with all the imported domains attached to it

    At the right side of each domain you will find an status indicator. NOT IMPORTED means that domain is not yet created on WHMCS, and IMPORTED means that the domain already exists (and can't be imported again).

    To update domain information for already imported domains, use the Domain Management screen.

    Import

    11.1 Filters (Import domains)

    This module has filters to search for domains in the list, you can filter by: Domain name and TLD.

    11.2 Import

    Select one or more domains from the list, choose a customer from the dropbox and click the Import to WHMCS and assign to selected customer button. The domains will be copied to your WHMCS database and assigned to that customer as it was registered normally.

    Select domains that are already imported will be ignored.

    12 Deleted domains

    The Deleted module is found in the Domain Management section Manage domains > Deleted and allows us to list all the deleted domains of the configured API user.

    Deleted

    13 Manage contacts

    The Contacts module is found in the Manage domains section Manage domains > Contactos and allows us to list the contacts of the established API user.

    Contacts

    13.1 Filtros (Contacts)

    This module has filters to search for contacts in the list, it allows us to filter by the following fields: Name, Email, verification and Designated Agent.

    13.2 Contacto

    From the Contacts list you can access a specific contact, this view offers more detailed information about the contact and the possibility of resending the verification email.

    Contact

    14 WHOIS

    This feature is comprised of two parts that allow to set up a simple whois proxy locally to perform domain availability checks from WHMCS (also known as "Whois lookup").

    14.1 Set up

    The whois proxy can be configured either in the Whois Proxy section Whois Proxy > Configuration or in the Admin sectionAdministration > Configuration > Whois Proxy.

    • WHMCS Domain: The domain where WHMCS is installed.
    • Allowed IP address: List of allowed IP's to do WHOIS searches. Please, refer to Access control section.

    Whois Configuration

    Finally, to configure every TLD to make use of the whois proxy, you should go to the left menu Whois Proxy.

    Click the button Change to MrDomain (next image) to configure each TLD automatically. Your whois.json (or whoisservers.php in WHMCS 6) will be modified so WHMCS uses the MrDomain API to check domains in those TLDs from that moment on. You don't need to make any other changes.

    Whois

    Permissions

    If you see a message informing you that the whois.json file (or whoisservers.php in WHMCS 6) does not have writing permissions, you will need to change the permissions of this file to allow the web server to modify it. Otherwise, you'll need to change its contents manually.

    Access control
    Due to the high demand that usually this kind of services have and the limited amount of API calls you can perform, it's recommended to restrict outside access to the proxy using the IP filters or another type of protection of your choice. Access the Settings section of the addon and configure access control for the Whois Proxy before continuing.

    Backups The addon has a built-in import/export option designed to make backups of your whois server file file. We heavily recommend doing a backup of this file before making any changes. A bad configuration in this file may render WHMCS unable to perform domain availability checks for domain registrations and transfers. It's a good idea deleting old backups periodically.

    14.2 Manual set up for WHMCS 6

    If your web server is unable to write to the whoisservers.php file, you will need to change it manually. To do so, browse to your /path/to/whmcs/includes/ folder and edit the file with your preferred editor.

    Search in the file the TLD or TLDs you want to configure. They should look like this:

    .me.uk|whois.nic.uk|No match

    Change it to look like this:

    .me.uk|http://www.yourwhmcsdomain.com/modules/addons/dondominio/whois/whoisproxy.php?domain=|DDAVAILABLE

    Where http://www.yourwhmcsdomain.com/ is the domain to access your WHMCS frontend. You may make this change on as many TLDs as you need.

    14.3 Manual set up for WHMCS 7

    The file in WHMCS 7 for whois servers has been changed to a JSON file and is stored in a different location than its WHMCS 6 counterpart.

    You'll find it in /path/to/whmcs/resources/domains/ with the name whois.json.

    If you want to configure manually a whois server in this file, you'll need to find the correct entry for the TLD you want to modify and adjust it.

    An entry looks like this in the file:

    [
    ...
    {
        "extensions": ".com,.net,.es,.com.es,.nom.es,.gob.es,.edu.es",
        "uri": "socket://whois.crsnic.net",
        "available": "No match for"
    },
    ...
    ]

    Adjust the "uri" and "available" fields, like this:

    [
    ...
    {
        "extensions": ".com,.net,.es,.com.es,.nom.es,.gob.es,.edu.es",
        "uri": "http://www.yourwhmcsdomain.com/modules/addons/dondominio/whois/whoisproxy.php?domain=",
        "available": "DDAVAILABLE"
    },
    ...
    ]

    Where http://www.yourwhmcsdomain.com/ is the domain to access your WHMCS frontend. You may make this change on as many TLDs as you need.

    14.4 Usage

    To perform WHOIS searches you should go to the top menu Utilities > WHOIS Lookup.