Billing for FusionPBX with FreeSWITCH

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


Current version 1.5.0.

  1. Billing for FusionPBX installation
  2. Billing for FusionPBX configuration
  3. Maintenance Tasks
  4. Default Settings
  5. LUA and FreeSWITCH Variables

Assumptions: The reader is familiar with Linux and FusionPBX. This manual also assumes you already have LCR installed.

Billing for FusionPBX Installation

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

  • You need to have FusionPBX 4.4 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 the PHPShadow extension installed. If you already have the LCR for FusionPBX working, you already have this.
  • You need to have LCR for FusionPBX installed. The Billing for FusionPBX uses the LCR software.
  • 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 a 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 hang calls up 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.

NOTE: If you are upgrading from any version to 1.5.0, crontabs have been moved to the resources/tools/ directory. You have to adjust your crontabs.

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

RPM Installation

This method only applies if you are using the RPM's from the OKay's repository. The installation method is very similar to the LCR one. If you haven't installed the LCR, the RPM dependency engine will install it for you. However, please read the LCR Manual to understand some LCR specific tasks.

  1. Type yum install fusionpbx-billing
  2. Go to Advanced->Upgrade menu, select Schema and Menu Defaults
    fusionpbx upgrade
  3. Go to Advanced->Group Manager and review the Billing permissions, you should have it at least for the superadmin.
  4. Log out and log in again into FusionPBX.
  5. Configure the Enhanced XML CDR Importer. You will need now to replace the standard CDR Importer that comes with FusionPBX and use the Enhanced CDR XML Importer. This depends on how you are using it.
    1. if you are importing after the call ends, you will need to modify the /etc/freeswitch/autoload_configs/xml_cdr.conf.xml file and change the following tag.
      from: <param name="url" value=""/>
      to: <param name="url" value=""/>
      Make sure the path matches. After that, just reload the mod_xml_cdr module.
    2. if you are using the crontab approach, you will need to find the given crontab and just change the script to call.

Source Installation 

  1. Go to app directory where FusionPBX is installed, for example: cd /var/www/html/fusionpbx/app. If you are using the default FusionPBX installation script, it is very likely the path is /var/www/fusionpbx/app.
  2. Copy Billing for FusionPBX in the server (by FTP or SCP), you can place it in /tmp directory
  3. Inside the app/ directory, 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 the key is your license number. Since version 1.0.1 license name can have any name with .key extension.
  5. Go to Advanced->Upgrade menu, select Schema and Menu Defaults
    fusionpbx upgrade
  6. If you are planning to cut the call when it runs out of credit, 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. Please make note that by default, FusionPBX doesn't install mod_nibblebill. You will need to manage yourself to get that installed.
  7. Log into FusionPBX as superadmin and go to System->Modules menu, enable and start the Niblebill module.
  8. Go to Advanced->Group Manager and review the LCR permissions, you should have it at least for the superadmin.
  9. Logout and login again into FusionPBX
  10. Install the fusionpbx-enhanced-xml-importer.

License Installation

Go into / your Billing directory (usually /var/www/html/fusionpbx/app/billing or the right directory where you installed) and execute echo -n key > any_name.key command, where the key is your license number. Since version 1.0.1 license name can have any name with .key extension. You don't need to do this if you hold an IP license; IP licenses can be obtained only if you donate to convert the project into open-source.

FusionPBX Patch or Default Settings

You may want to apply the patch xml_cdr_inc.php.diff. From the FusionPBX root directory, type: patch -p0 < app/billing/resources/patches/xml_cdr_inc.php.diff. If you are not able to do this or you don't want to alter your installation you can always set up the following default settings:

  • Category: CDR
  • Sub-Category: field
  • Type: array
  • Value: call_sell_local_currency and local_currency (two entries).

The default settings approach is preferred.

Billing for FusionPBX Configuration

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

A Profile is used to define who to charge. Each profile is identified by a unique label that is linked directly to the accountcode variable.
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.
The specific amount, on post-paid profiles, establishes the maximum credit a profile may have (negative number). 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/Pricing List
A tag that defines what pricing list to use. By changing this label, you may have more than one pricing list.
Referal fields let you reward your users just because they recommend your service.

Billing Profile Configuration

  1. Go to Apps->Billing menu and add a profile
  2. Fill in the next information
    fusionpbx add new billing
    Select FROM and TO depending on who shall send the billing to who. Data will be taken according to information in the Contacts application; you can go to App -> Contacts menu to fill in the information.
    In most cases, using billing per tenant (domain) 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. This value is the one you will need to match with the accountcode variable to know who to charge.
    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/Pricing list field will tell the profile what pricing list to use. By default, it is 'default'.
    Referal fields are sued to reward your users because of recommendations.

    New billing releases may have more options.

Remember to fill the accountcode field with the correct value when creating items in FusionPBX. Accountcode by itself is just a variable, depending on your call flow you may configure it at:

  • extensions,
  • variable dialplans.

If you don't know where to start, a good place is by configuring all the extensions with the proper accountcode value.

Dialplan Configuration

The Billing for FusionPBX software needs to have the cdr_billing variable set (any value). This is the way where you can decide what calls to bill or not. The best place to set this variable is in the "variable" dialplan (go to Dialplan -> Dialplan Manager menu option).

Currency Rate Configuration

Insert at least this record in the database:

INSERT INTO v_rate_conversions (rate_conversion_uuid, from_iso4217, to_iso4217, rate, rate_epoch) VALUES ('55e5796b-3aba-4b0a-aab2-299994c755a4', 'USD', 'USD', 1, 0);

If your default currency is different than the USD, you will need to do the same equivalent SQL query. This query won't be necessary for future releases.

After that, sign up for a currency rate API key at and configure the following default setting:

  • Category: Billing
  • Sub-Category: currency_converter_api
  • Type: text

Run the following command for the first time from the FusionPBX root directory: php app/billing/billing_crontab_currency_rate.php. If you are planning to have customers or carriers that use a mix of currencies, for the sake of speed, it is a good idea to set this crontab at least every 24 hours. This is totally optional, the software will query the API as needed.


Deals will allow you to give specials. Read our deals document to understand how it works.

Auto Top-Ups and Low Balance Alerts

(It will be soon here)

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
  3. billing_crontab_auto_topup.php
  4. billing_crontab_lowbalance_email.php

Follow this crontab example:

* * * * * cd /var/www/html/fusionpbx && php app/billing/billing_crontab_auto_topup.php

Configure the crontab frequency as your need it. It is important to call the scripts from within the FusionPBX directory.

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.

Default Settings

Category Sub Category Type Values Default Value
billing earning_rate numeric
  • float value. 1.0 means no earning, 1.10 means 10% profit.
billing payment_amount array
  • float or integers of the fixed options to accept a payment. Use this to force always payments of the same amounts. The payments are specified in the local currency, if the local currency is less than the minimum payment, it won't be shown.
billing minimum_payment numeric
  • a float indicating the minimum payment the software will accept. If the currency of the customer is other, it will be converted first.
billing minimum_payment_currency text
  • the currency of the minimum payment.
billing offline_enabled
  • false: disables the PLUGIN for payments.
  • true: enables the PLUGIN for payments.
billing offline_debug
  • false
  • true
billing offline_message_LANGUAGE
  • A text to display in the payment plugin. Change LANGUAGE for the language code such as en, es, fr.
billing offline_postpaid_capable
  • false: disable this plugin for postpaid customers.
  • true: enable this plugin for postpaid customers.
billing offline_prepaid_capable
  • false: disable this plugin for prepaid customers.
  • true: enable this plugin for prepaid customers.


  • float number of the percentage fee to take of before applying the balance. PayPal fee goes from 2.9%, then the value would be 2.9. 
billing offline_fixed_comission_currency
  • The currency used to discount the fixed fee.
Billing default currency, or USD
billing offline_fixed_comission
  • The fixed fee to take before applying the balance. PayPal's fixed fee is 0.30 USD, then the value would be 0.30.
billing offline_default_charge
  • a float number that is prefilled when a customer is going to pay.
billing offline_minimum_payment
  • a float to specify a minimum payment per plugin.
Global minimum payment or 0
billing paypal_testmode
  • false: charges actual money with PayPal.
  • true: uses the PayPal sandbox.
billing paypal_seller_id text
  • PayPal registered email that can receive funds.
billing paypal_domain text
  • a domain name that the software will send to let know PayPal where it should push the IPN.
billing stripe_publishable_key text
  • your stripe publishable key. It will be used if stripe_test mode is false.
billing stripe_secret_key text
  • your stripe secret key. It will be used if stripe_test mode is false.
billing stripe_publishable_test_key text
  • your stripe publishable test key. It will be used if stripe_test mode is true.
billing stripe_secret_test_key text
  • your stripe secret test key. It will be used if stripe_test mode is true.
billing paypal_callback_file
  • an absolute path to the file that has a routine that will be called each time someone makes a payment.
billing paypal_callback_function
  • name of the function that is going to be called.
billing debug boolean
  • false
  • true
billing https boolean
  • false: uses plain HTTP for internal HTTP calls.
  • true: forces HTTPS for internal HTTPS calls. Turn this on if you are forcing all to use HTTPS.
billing http_project_path boolean  
billing invoice_first_caracters numeric
  • an integer value of how many characters it will use from the contact organization to start numbering your invoice. If you put 4 and the company name is OKay Inc, invoices will be OKAY9999999. This value is used when using the internal invoicing system.
billing invoice_image1
  • Paths of the images to attach to the invoice email. Use this if you are using the internal invoicing system.
billing invoice_message text
  • text to append in the invoice email. Use this if you are using the internal invoicing system.
billing invoice_subject text
  • text of subject on the invoice emails. Use this if you are using the internal invoicing system.
billing invoice_cc text
  • email of carbon-copy for the invoice emails. Use this if you are using the internal invoicing system. If you are going to CC to more than one email, use the comma.
billing invoice_bcc text
  • email of blinded-Carbon-copy for the invoice emails. Use this if you are using the internal invoicing system. If you are going to BCC to more than one email, use the comma.
billing pyramid_message text
  • text to add to the reward email.
billing currency text USD
billing extension_price
  • a float value of how much to bill per item using the currency specified by the default setting.
billing extensions_for_free
  • an integer value of how many items per customer will be excluded from being charged.
billing deals_realtime boolean
  • false: don't apply the price correction of any deal in real-time.
  • true: apply the price correction of any deal in real-time. The CDR will have the adjusted price.
billing invoice_only_superadmins var
  • 0: all the contacts in the FROM field of the billing profile will be listed.
  • 1: only super-admin contacts in the FROM field of the billing profile will be listed.

This variable will be fixed in future versions.

billing currency_database_cache_ttl numeric
  • an integer that sets the TTL for the currency cache.
billing currency_converter_api text  
billing whmcs_url text
  • full HTTP URL of the WHMCS api.php interface.
billing whmcs_identifier text
  • API identifier
billing whmcs_secret text
  • API secret
billing whmcs_http_user text
  • HTTP authentication user
billing whmcs_http_password text
  • HTTP authentication password
billing whmcs_billableitem_decimals text
  • an integer indicating the number of decimal places the software will round when placing a charge into the WHMCS.
billing whmcs_record_zeroes boolean
  • false: do not send a billable item if the charge of the item is zero.
  • true: send always the charge even if it is a free charge.
billing whmcs_billableitem_invoiceaction text
  • nextcron: the item will be invoiced when the WHMCS crontab runs.
  • nextinvoice: the item will be appended to the next customer invoice.
  • duedate: the item will be invoiced when the billion cycle ends. This day is defined in the billing profile.
billing ca_verification boolean
  • false: the software won't verify the SSL certificates. Use this if you have an old PHP version with an outdated CA chain or use self-signed certificates.
  • true: verifies the HTTPS connections.
billing short_duration_acceptable_percentage numeric
  • a float indicating the maximum percentage of short-calls before applying a surcharge.
billing short_duration_charge numeric
  • a float indicating a fixed surcharge when a short duration happens. If the currency is different, it will be converted before being billed.
billing short_duration_currency text
  • the currency of the short-duration surcharge.
the billing default currency or USD
billing short_duration_time numeric
  • an integer indicating the maximum call duration to be considered a short call. All calls between zero and this value are short calls.
billing auto_topup_message text
  • the text to send in an email. If the first character starts with an @, you can specify a route to a file. Use the template that is included.
billing low_balance_alert numeric
  • The minimum balance to trigger the low-balance email. Currency is specified in the currency default setting.
billing low_balance_message text
  • the text to send in an email. If the first character starts with an @, you can specify a route to a file. Use the template that is included.

LUA and FreeSWITCH Variables

LUA Variable FreeSWITCH Variable Values Default Value
  • false
  • true: executes the billing part on the LCR engine. It will add all the needed variables for post-processing.
lcr.billing_dynamic_price lcr_billing_dynamic_price
  • false: use strictly the prices from the selling pricing list.
  • true: calculate the selling price on the fly with a profit margin.
lcr.billing_dynamic_earnings lcr_billing_dynamic_earnings
  • a float indicating the profit margin. If 0.50, it means it will add 50% of the buying price.
lcr.billing_default_list_fallback billing_default_list_fallback
  • false: doesn't look into the default pricing list for a missing rate. The price will be for free.
  • true: looks into the default pricing list if the main pricing list doesn't have the required rate.
  • name of the default pricing list to fallback.
lcr.billing_list_required billing_list_required
  • false: allows a free call if the selling rate is missing from the main and the fallback selling pricing list.
  • true: if the rate is not present in the main pricing list or the fallback, the call is not routed.
lcr.strict_earnings lcr_strict_earnings
  • 'relaxed': allows routing even if there is a loss (selling price is lower than buying price).
  • 'strict': only allows routing when there is a profit (selling price must be greater than buying price).
  • a float: routes only if the profit is greater than the required. If you want only to route if you do a 10% profit, put 0.10.
  • the code that links the call to the billing profile
  • any value: it allows the call to be billed by the Enhanced XML CDR Importer.
  • unset: the call won't be billed.
  • an integer with the connection rate
  • an integer with the talking rate
  • an integer with the first increment that applies to lcr_user_first_rate
  • an integer with the talking increment that applies to lcr_user_second_rate
  • the currency of lcr_user_first_rate and lcr_user_second_rate
Billing default currency or USD



  • Billing retroactive rewritten
  • Crontab scripts moved to a directory
  • New email templates
  • Logic bug fixes
  • FusionPBX 4.5.35, 5.0 compatibility


  • New billing_card_* permissions
  • Auto top-up for Strip plugin
  • Tag support for auto-pricing script
  • Low balance email warning
  • PostgreSQL compatibilities
  • New DISA Lua Script

  • Fix a bug that prevents deleting a billing profile
  • Recursive queries fix


  • Auto-pricing script
  • Fix a bug that prevents adding new billing profiles when using PostgreSQL
  • More memory to the HTTP export script
  • Fix recursive queries
  • Payment plugins now use more default settings (soon plugin_config.php file will be useless)
  • Callback support when getting a payment


  • WHMCS SSL certification can be disabled by using a default setting
  • Date range bugs were fixed
  • Billing crontab proxy support (very useful when you have a cluster)


  • Support to get fixed payment amounts.
  • Amazon MariaDB 10.2+ support.
  • CSV support to the HTTP export script.


  • Minimum payment support per plugin.
  • Deals support, you can now give first X minutes to a prefix at a flat rate.
  • Better billing by item.
  • Fix a bug with the currency API.
  • Export your selling rates in JSON format.
  • Force payment in full.
  • Static items charge logic fixed.


  • Some bugs when you create a new billing profile were fixed.
  • New support to charge for short calls.
  • More default settings to customize WHMCS integration.


  • Cosmetic fixes.


  • 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.


  • Force a customer to pay the balance in full.
  • Currency conversion API updated, you will need to get your own API key from
  • 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.


  • In the retroactive script, you can bill for passed calls.
  • Cosmetic fixes.


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


  • Bugfixes.


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


  • 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

  • Bugfix that prevents installation in brand new deployments.


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


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


  • 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.


  • Useless fields are now hidden.


  • 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.
  • The 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.


  • 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.

Since 1.3.0, the Billing for FusionPBX has support for deals. A deal is an easy way to overwrite the rate of certain destinations based on some conditions. You will be able to offer deals such as:

  • The first 60 monthly minutes of outbound calls to the 1613 area code will be for free.

Read more: Deals Configuration with Billing for FusionPBX

About OKay

An IT Company whose mission is generating value with low cost of ownership.

We will offer you Linux based solutions that satisfy your needs. We focus on VoIP & Linux, but we are up for any other challenge you may want to bring.