Billing for FusionPBX with FreeSWITCH

• FusionPBX
• Billing
• FreeSWITCH

This manual will guide you on every detail about how to install and use the Billing for FusionPBX native application.  If you want to have a quick setup, you may read the quick guide and later return here.

Content

1. Billing for FusionPBX installation
2. Billing for FusionPBX configuration
3. Maintenance Tasks

Billing for FusionPBX Installation

Before you start Billing for FusionPBX installation, you must satisfy the next requirements:

• You need to have FusionPBX 3.6 or better installed with MySQL, MariaDB or PostgreSQL as database data storage.  If you don't know how to do this, OKay offers Linux consultant services.
• You need to have PHPShadow extension installed. If you already have the LCR for FusionPBX working, you already have this.
• You need to have LCR for FusionPBX installed.
• You need to have SSH access and to be able to write in /app directory where FusionPBX is installed.
• You need to have access to FusionPBX as superadmin.
• You need to download and get a Billing for FusionPBX license.
• Optionally, you may need to install mod_niblebill. The billing software uses this module to hangup calls when you run out of credit. If this is not important for you, you may skip it. The installation procedure depends on how you installed FreeSWITCH: source, DEB's or RPM's.

When you satisfy these requisites, please follow the next steps:

1. Go to app directory where FusionPBX is installed, for example: cd /var/www/html/app. If you are using OKay's RPM type yum install fusionpbx-billing.
2. Copy LCR for FusionPBX in the server (by FTP or SCP), you can place it in /tmp directory
3. Execute the command tar -jxvf /tmp/billing-crypted.tar.bz2
4. Go into /var/www/html/app/billing directory and execute echo -n key > any_name.key command, where key is your license number. Since version 1.0.1 license name can have any name with .key extension.
5. Copy niblebill.conf.xml into autoload_configs directory (for example: /etc/freeswitch/autoload_configs/).cp niblebill.conf.xml /etc/freeswitch/autoload_configs/. Edit niblebill.conf.xml file and change the DSN values with yours. You can get the DSN value from the /etc/fusionpbx/config.lua file.
6. Log into FusionPBX as superadmin and go to System->Modules menu, enable and start the Niblebill module.
7. Go to Advanced->Upgrade menu, select Schema and Menu Defaults
8. Review groups and menu permits. Go to Advanced->Group Manager and review that at least, superadmin group has the billing permissions.
9. Logout and login again into FusionPBX
10. If you are using the RPM's, install the fusionpbx-enhanced-xml-importer by typing yum install fusionpbx-enhanced-cdr-importer. Otherwise, go to your app/ directory and do a git clone https://bitbucket.org/okay-network/fusionpbx-enhanced-cdr-importer/src/master/ enhanced-cdr-importer. The name is hardcoded in many places, don't use another.
11. Edit your /etc/freeswitch/autoload_configs/xml_cdr.conf.xml file and change the URL parameter to http://127.0.0.1/app/enhanced-cdr-importer/xml_cdr_import.php
12. Reload the mod_xml_cdr module or restart the FreeSWITCH daemon.
13. Edit a dialplan (usually the variables dialplan) and set the variable cdr_billing=1 (the value doesn't matter, the variable must exist). If you unset the variable, you can pass free calls (not billed). By default, you should bill everything unless you have a special business need.

Billing for FusionPBX Configuration

To configure LCR for FusionPBX, you need to understand the following concepts:

Profile

A Profile is used to define a billing. Each profile is identified by a unique label.

Billing Cycle

A Billing Cycle defines the billing day. Static charges will take place this day.

Billing Type

A billing type may be pre or postpaid.

Amount

The specific amount, on post-paid profiles it establishes the maximum credit a profile may have. This value is zero for pre-paid profiles. You must define billing currency, the system will use external services to do the rating.

LCR profile

LCR profile is a pricing list. By changing this label, you may have more than one pricing list.

Refered

Referal fields let you reward your users just because they recommend your service.

After:

1. Go to Apps->Billing menu and add a profile
2. Fill the next information
   Select FROM and TO depending who shall send the billing to who. Data will be taken according to information in Contacts application; you can go to App -> Contacts menu to fill information.
   In most cases, using billing per tenant is enough, but there are specific cases where an alternate code is required, especially if you need more than one billing profile per tenant; in this case, select the by-code option. The value entered in the Criteria Value field needs to be in place on all other FusionPBX items.
   Select the billing day cycle, to make things simple it is only allowed from 1 to 28.
   The Amount field is read-only, you must select the currency for billing. Once the currency is set, you won't be able to change it.
   Delay days field is not used.
   Balance is a read-only field.
   LCR profile field will tell the profile what pricing list to use. By default it is 'default', by adding a new profile means to modify file lcr.conf.xml.
   Referal fields are sued to reward your users because of recommendations.

Remember to fill the accountcode field with the correct value when creating items in FusionPBX. After having your first billing profile ready, you need to change the bridging statements to lcr/default/XXXXXX, usually lcr/default/$1. It depends on your dialplans. The default profile will pass the information you need to bill properly.

Maintenance Tasks

Crontab Configuration

The following files can be edited and place into a crontab:

1. billing_crontab_pyramid.php
2. billing_crontab_lowbalance_email.php

Billing Logic Change

Sometimes, you may need to change billing logic (only in specific cases). You can edit the file resources/functions/ratings.php

Billing for FusionPBX Update

You may follow the installation procedure for any update.

• FusionPBX
• Billing
• FreeSWITCH
• Changelog

1.2.2

• Cosmetic fixes

1.2.1

• Database currency rate cache. Use the following default setting category: 'billing', subcategory: 'currency_database_cache_ttl', type: 'numeric' to specify a TTL (in seconds). If you specify a negative number, the cache won't expire. You can manipulate this table to use your own rates.
• Multiple fixes when using account code different than the domain
• More WHMCS work to make the integration easier. Billable items can be pushed to be invoiced on the next cron, next invoice or a fixed due date.

1.2.0

• Force a customer to pay the balance in full.
• Currency conversion API updated, you will need to get your own API key from https://www.currencyconverterapi.com/
• Currency API updated to v7
• All default settings using dot are now deprecated (still useful), use the lower dash. For example, paypal.debug is now paypal_debug.
• More WHCMS fixes.
• Disable the payment button after pressing it, it will prevent double charges.
• Minimum payments. You can specify a general minimum top-up amount or per payment plugin.

1.1.7

• The retroactive script, you can bill for passed calls
• Cosmetic fixes

1.1.6

• Postpaid Customers now can be forced to pay the balance in full
• The quick profile import tool
• Cosmetic fixes

1.1.5

• Bugfixes

1.1.4

• Bugfixes
• Static billing items are rewritten
• New database fields
• WHMCS support, you can now invoice

1.1.1

• Bugfix that prevents the correct charge of static items when using multi-tenant and mixing billing profiles
• Many speed improvements
• Since Yahoo! Finance has closed its currency converting service, we have switched to curencyconverterapi.com

1.1.0.1

• Bugfix that prevents installation in brand new deployments

1.1.0

• TAXes logic was improved, they are added when you are paying
• The Stripe/Offline payment add-ons are now included

1.0.8

• IDR currency support
• Labelling changes of LCR Profile to be more understandable
• Minor fixes

1.0.7

• New default settings to allow to disable experimental features
• Better support for FusionPBX 4.0
• Fix PayPal IPN issue that prevents balance application under some conditions
• Allow showing the updated balance after paying with PayPal

1.0.6

• Useless fields are now hidden

1.0.5

• More fault tolerable
• More credit for post-paid profiles
• Paypal, Stripe and Offline payments plugins now use Default Settings. File config is supported for compatibility
• Paypal payment plugin now supports auto top-ups
• HTTPS now can be selected as the default protocol
• Better support for websites with 301/302 answer codes
• Postpaid invoices with CC and BCC support
• Better support for PostgreSQL

1.0.4

• Better Support for FusionPBX 3.7
• New 'default settings' to control pyramid message
• New script to send billing messages to post-paid users
• Recurrent payments for Paypal Support
• nibblebill.conf.xml file fixes
• Commission deduction support for payment gateways, in % or fixed quantity

• FusionPBX
• Billing
• FreeSWITCH

The application architecture within the /app directory of FusionPBX allows a very quick installation. Please follow the following steps:

Install ShadowPHP

ShadowPHP is encryption technology that Billing for FusionPBX uses. It is important to properly install this component.

1. Download the server extension to the version of PHP running. The extension can be downloaded from http://phpshadow.com/download.php.
2. Inside, you will find the downloaded extension file phpshadow.so, copy it into the directory of modules. If you do not know the route, the php command php -rr "echo ini_get ('extension_dir');" will show you the route.
3. Edit the php.ini file and add the line extension = phpshadow.so, some Linux distributions have php.d directory, you can put into a single file and add the line.
4. Restart your apache server.

If you are in doubt about how to configure ShadowPHP extension, you will find this site http://phpshadow.com/download.php very useful. There is a User Guide (in English) that explains step by step how to install.

Download and Install the LCR and Billing for FusionPBX

The next step is to install the software as such. Please download both applications. The Billing application requires LCR. FusionPBX must be configured with a database backend such as MySQL (or MariaDB) or PostgreSQL. Follow the following steps:

1. Download both applications.
2. Copy both .tar.bz2 extension files into FusionPBX server. In this example we will assume that both files are in the /root directory and FusionPBX is installed in /var/www/html directory.
3. Change to /var/www/html/app directory.  Here is where applications are. You can type cd /var/www/html/app.
4. Expand both tar.bz2 files with tar -jxvf /root/lcr-crypted.tar.bz2 and tar -jxvf /root/billing-crypted.tar.bz2 commands.
5. Run php /var/www/html/core/upgrade/upgrade_schema.php. The command will display various SQL statements that indicate that they are building the necessary tables in the database.
6. Log into FusionPBX as a super-administrator and go to the menu System-> Menu Manager, edit the default menu (default) and select the option Restore defaults.
7. Go to the menu Advanced-> Group Manager and edit the permissions of the super-administrators group. Check that the permissions for LCR and Billing are checked.
8. Install the Enhanced XML Importer, change to /var/www/html/app directory and type git clone https://bitbucket.org/okay-network/fusionpbx-enhanced-cdr-importer/src/master/ enhanced-cdr-importer
9. Edit the /etc/freeswitch/autoload_config/xml_cdr.conf.xml file and edit or add the following line:
   <param name="url" value="http://127.0.0.1/app/enhanced-cdr-importer/xml_cdr_import.php"/>
10. Reload the mod_xml_cdr module, you can type reload mod_xml_cdr from the FreeSWITCH console.

Installation Using RPM's

If you are using CentOS 6, 7 and 8 you can do the following:

1. Install the OKay RPM repository, follow directions on this page.
2. After the repository is installed, type: yum install fusionpbx-all, confirm the questions and wait.
3. Finish the installation by accessing to http://IP/fusionpbx/, use the following default data (you can change it):
   • database name: fusionpbx
   • database username: fusionpbx
   • database password: c4rl0s3l4rt1st4
   • database host: 127.0.0.1

At this time the application is ready to be configured.