05. WHMCS integration manual

WHMCS integration manual

This document is not WHMCS usage manual. Purpose of this document is to inform user on subject of integrating BlissRADIUS with WHMCS. For detailed information on how WHMCS works visit WHMCS documentation center Knowledge on subjects of Products and Services and Automation Settings can greatly help.

Integration overview

• Integration is achieved using WHMCS provisioning module. Communication is via TCP socket, always initialized one-way from WHMCS host to BlissRADIUS host on admin port (default 8800).

• Multiple WHMCS hosts can be connected to single BlissRADIUS server.

• All WHMCS service actions are supported ('CreateAccount', 'SuspendAccount', 'UnsuspendAccount', 'TerminateAccount', 'Renew', 'ChangePassword', 'ChangePackage'). BlissRADIUS must be running and connectable at the moment each action occurs for synchronization to be complete. There is no caching.

• Each WHMCS product matches one BlissRADIUS account type. Editing or deleting them from WHMCS portal immediately synchronizes data with BlissRADIUS via WHMCS action hooks ('ProductEdit', 'ProductDelete').

• Each WHMCS service matches one BlissRADIUS user account. Multiple services (BlissRADIUS user accounts) per WHMCS client are possible. If client is deleted from WHMCS portal, all associated BlissRADIUS user accounts are immediately deleted by WHMCS action hook ('ClientDelete').

• User accounts and account types in BlissRADIUS that are managed by WHMCS are marked as such in notes. Do not edit them from BlissRADIUS portal. If you do delete or change them, you must re-create or re-save services/products on WHMCS end to correct state.

• BlissRADIUS keeps track of username uniqueness as it is crucial for RADIUS authentication. If you select already reserved username on WHMCS end, you will get warning and have to select another one. Changing username is performed via custom service action ('ChangeUsername').

• User accounts and account types created via BlissRADIUS portal are not visible to WHMCS and can be used independently without any restrictions, except for username/name uniqueness.

Installing and upgrade

• Create target folder 'modules/servers/blissradius/' in WHMCS installation folder and make it writeable by web server process. It is required so auto upgrade can keep files in sync with BlissRADIUS.

• Copy files from 'shared/integration/whmcs' folder in BlissRADIUS installation to target folder in WHMCS.

• Edit 'config.php' in target folder and set correct value for BlissRADIUS IP address.

• Login to BlissRADIUS admin portal and under Configuration > Settings > Integration tab add WHMCS IP address to list of allowed hosts. If you are connecting more than one WHMCS host, then you must set unique integer ID for each host.

WHMCS now has BlissRADIUS module integrated and both sides are opened for communication.

There is no need for copying files again after upgrading BlissRADIUS. WHMCS module will make sure local files on WHMCS server are in sync with new version of BlissRADIUS.

There might be need to re-check all product module settings. Next chapter descibes it in detail.

Product setup

• Login to WHMCS admin portal and go to Setup > Products/Services

• Create a New Group, name it RADIUS.

• Create a New Product of type 'Other Product/Service', select it to be member of group we just created and name it 'Internet service'. It should be immediately visible in BlissRADIUS account types report.

• Go to edit menu for product and under 'Module settings' tab select 'blissradius' module from list. Configure shown parameters.

If BlissRADIUS upgrade adds new fields to Module Settings then you must check and re-save all products again, even if you make no changes. Reason is that WHMCS populates new fields with incorrect default values, leading to undesirable results. Always check BlissRADIUS change log for this.

Custom fields

There are number of parameters that can be set on per-user level using WHMCS custom fields thus overriding product parameters. Keep in mind that those fields may or may not be visible during purchase and that they can not influence price (use configurable options for that).

You have to set up custom fields for each product separately under 'Custom fields' tab of Product/Services edit page.

Available custom parameters are listed below. Fields must be named exactly as specified.

• Max. Sim. Use - Overrides product parameter by same name. If empty or not present, products parameter value is used.

• Framed IP Address - Same as above.

• RADIUS Attributes - Same as above.

• Email Address - Comma separated list of e-mail addresses that will receive notifications regarding state of this service. If empty or not present, service owners e-mail address is used.

• Phone Number - Same as above, only with phone numbers.

• MAC/CallingID - MAC/CallingID parameter. Depending on how you configure BlissRADIUS, this can be used for eg. to either autologin client using his MAC address, or to restrict connections only to single MAC. Check FAQ and User Manual for more details.

Configurable options

Configurable options serve same purpose as custom fields. Main difference is that they can change purchase price depending of value entered/selected.

To create configurable options go to Setup > Products/Services > Configurable Options, create new option group and assign it to 'Internet service' product.

Available configurable options are listed below. Fields must be named exactly as specified.

• Total Usage Limit - Overrides product parameter by same name. If empty, zero or not present, products parameter value is used.

• Download Limit - Same as above.

• Upload Limit - Same as above.

• Rate Limit - Same as above.

• Time Limit - Same as above.

• Service Duration - Same as above.

Product ordering

Select client and place a new order for 'Internet service'. Once product is activated, new user account should be visible in BlissRADIUS users report.

If you want to enable clients to change options after purchase (eg. top up their gigabyte or time limit, like shown on image) then you must enable it for each product separately under 'Upgrades' tab on product edit page.

Service management

Any change to user data would require call to appropriate service action from WHMCS admin portal. Eg. changing username would require 'Save', then 'Change Username' service action. Same goes for password and 'Change Password' or product change, rate, time or usage limits and 'Change Package' action. If username is not set, clients e-mail is used by default. Configuration options will be grouped together (marked red in picture) as well as custom fields (marked green).

Most, if not all actions require apropriate button (marked blue) to be clicked after 'Save'. Always keep an eye on actual user details (marked yellow). Values like username or password that are in input fields may differ from actual user details (marked yellow) if sync is not done properly or desired username is not available.

If you want to delete single service, you must call 'Terminate' action first. Deleting client will remove all associated services (BlissRADIUS user accounts) but deleting single service without 'Terminate' call will not.

If you set service to be reoccurring, each scheduled 'Renew' action will by default reset usage to zero and limits to starting values. This can be changed in product settings.

For more information refer to WHMCS user documentation.

Automated renewal

For reoccuring services WHMCS integration works using BlissRADIUS internal scheduler. This feature is in effect since BlissRADIUS version 3.5.11 and changes old behaviour that relied on WHMCS renew module actions.

Renewal is controled by 'Auto Renew' field in 'Setup > Products/Services > Edit > Module' tab . Service is renewed shortly before it expires (Service Duration is reached). 'copy' and 'reset' flags control if limits are to be copied from previous service or reset to product default.

Keep in mind:

• Auto renew is not affected by WHMCS invoices and billing.
• Once service is created, it will be renewed until terminated.
• Suspended services will also be renewed, but will stay suspended.

Client portal

Log in to client portal with user you just added Service to. Under 'My Services' select 'RADIUS - Internet service'. Service statistics are displayed, along with link to BlissRADIUS client portal for a complete overview.

Security considerations

BlissRADIUS admin portal should be available only to system administrators and operators. It should not be publicly accessible from Internet.

BlissRADIUS client portal should be publicly available, thus enabling anyone using WHMCS client portal to simultaneously access both services.

2024-09-27

BlissRADIUS Embedded™ 1.15 is out with postpaid license support.

2024-09-19

We are introducing changes to payment methods. See Home page for more details.

2023-07-06

BlissRADIUS Embedded™ 1.14 is out with new features.

2022-11-18

BlissRADIUS Embedded™ 1.13 is released with new fixes and features.

2021-12-31

BlissRADIUS Embedded™ 1.12 is out with new features.

2021-06-22

Volume discount for monthly BlissRADIUS™ licenses is available now.